Modulemd Utility Functions: Modulemd Reference Manual

## Modulemd Utility Functions Modulemd Utility Functions — Provides private utility functions for use within libmodulemd. |

## Stability Level

Private, unless otherwise indicated

## Functions

#define | UNUSED()
modulemd_tracer * | modulemd_trace_init ()
void | modulemd_trace_free ()
#define | MODULEMD_INIT_TRACE
GHashTable * | modulemd_hash_table_deep_str_copy ()
GHashTable * | modulemd_hash_table_deep_set_copy ()
GHashTable * | modulemd_hash_table_deep_str_set_copy ()
GHashTable * | modulemd_hash_table_deep_str_str_set_copy ()
gboolean | modulemd_hash_table_sets_are_equal_wrapper ()
gboolean | modulemd_hash_table_sets_are_equal ()
gboolean | modulemd_hash_table_equals ()
gint | modulemd_hash_table_compare ()
gint | modulemd_strcmp_sort ()
gint | modulemd_strcmp_wrapper ()
GPtrArray * | modulemd_ordered_str_keys ()
GStrv | modulemd_ordered_str_keys_as_strv ()
GVariant * | modulemd_variant_deep_copy ()
void | modulemd_hash_table_unref ()
gboolean | modulemd_validate_nevra ()
gboolean | modulemd_boolean_equals ()
gboolean | modulemd_is_glob_pattern ()
gint | compare_streams ()
gboolean | modulemd_fnmatch ()
gboolean | modulemd_rpm_match ()
guint64 | modulemd_iso8601date_to_guint64 ()
gchar * | modulemd_guint64_to_iso8601date ()
#define | MODULEMD_REPLACE_SET()
#define | MODULEMD_SETTER_GETTER_STRING_EXT()
#define | MODULEMD_SETTER_GETTER_STRING()
#define | MODULEMD_SETTER_GETTER_STRING_STATIC()
#define | modulemd_str_set_new

## Types and Values

#define | FALLTHROUGH

## Description

## Functions

### UNUSED()

    #define UNUSED(x) UNUSED_##x __attribute__ ((__unused__))

### modulemd_trace_init ()

    modulemd_tracer *
    modulemd_trace_init (const gchar *function_name);

#### Parameters

function_name | The name of the function being traced. |

#### Returns

A newly-allocated modulemd_tracer object.

Allocates and returns a new modulemd_tracer that tracks the provided `function_name` . Also writes a `g_debug()` trace message indicating `function_name` has been entered.

DIRECT USE OF THIS FUNCTION SHOULD BE AVOIDED. Instead use `MODULEMD_INIT_TRACE`--which makes use of this function as part of its internal implementation.

[transfer full]

Since: 2.0

### modulemd_trace_free ()

    void
    modulemd_trace_free (modulemd_tracer *tracer);

Writes a `g_debug()` trace message indicating the function name associated with `tracer` is being exited and frees `tracer` .

DIRECT USE OF THIS FUNCTION SHOULD BE AVOIDED. Instead use `MODULEMD_INIT_TRACE`--which makes use of this function as part of its internal implementation.

#### Parameters

tracer | A modulemd_tracer object representing a function being traced. |

Since: 2.0

### MODULEMD_INIT_TRACE

    #define             MODULEMD_INIT_TRACE()

When used at the beginning of a function, automatically writes `g_debug()` trace messages when entering and leaving that function. Makes use of `modulemd_trace_init()` and `modulemd_trace_free()`.

This macro manages the memory of the hidden modulemd_tracer object it creates, so the caller should not attempt to modify that object in any way.

Since: 2.0

### modulemd_hash_table_deep_str_copy ()

    GHashTable *
    modulemd_hash_table_deep_str_copy (GHashTable *orig);

#### Parameters

orig | A GHashTable to copy, containing string keys and string values. |

#### Returns

A newly-allocated GHashTable containing a deep copy of both the keys and values from `orig` .

[transfer full]

Since: 2.0

### modulemd_hash_table_deep_set_copy ()

    GHashTable *
    modulemd_hash_table_deep_set_copy (GHashTable *orig);

#### Parameters

orig | A GHashTable to copy, containing string keys. |

#### Returns

A newly-allocated GHashTable containing a deep copy of the keys from `orig` . The values from `orig` are ignored, and the values in the copy are set the same as the corresponding keys so the returned GHashTable can be used as a set.

[transfer full]

Since: 2.0

### modulemd_hash_table_deep_str_set_copy ()

    GHashTable *
    modulemd_hash_table_deep_str_set_copy (GHashTable *orig);

#### Parameters

orig | A GHashTable to copy, containing string keys and GHashTable values. |

#### Returns

A newly-allocated GHashTable containing a deep copy of the keys from `orig` . The corresponding GHashTable value for each key is deep copied via `modulemd_hash_table_deep_str_copy()` for use as a set.

[transfer full]

Since: 2.0

### modulemd_hash_table_deep_str_str_set_copy ()

    GHashTable *
    modulemd_hash_table_deep_str_str_set_copy
                                   (GHashTable *orig);

#### Parameters

orig | A GHashTable to copy, containing string keys and GHashTable values that are nested two levels deep. |

#### Returns

A newly-allocated GHashTable containing a deep copy of the keys from `orig` . Each corresponding GHashTable value is deep copied, with the second level GHashTable copied for use as a set as described in `modulemd_hash_table_deep_str_copy()`.

[transfer full]

Since: 2.0

### modulemd_hash_table_sets_are_equal_wrapper ()

    gboolean
    modulemd_hash_table_sets_are_equal_wrapper
                                   (const void *a,
                                    const void *b);

#### Parameters

a | A void pointer. |
b | A void pointer. |

#### Returns

TRUE if both `a` and `b` (considered as GHashTables) contain an identical set of keys, FALSE if they differ.

Only the keys of `a` and `b` are compared. The values are ignored.

Since: 2.2

### modulemd_hash_table_sets_are_equal ()

    gboolean
    modulemd_hash_table_sets_are_equal (GHashTable *a,
                                        GHashTable *b);

#### Parameters

a | A GHashTable object. |
b | A GHashTable object. |

#### Returns

TRUE if both `a` and `b` contain an identical set of keys, FALSE if they differ.

Only the keys of `a` and `b` are compared. The values are ignored.

Since: 2.0

### modulemd_hash_table_equals ()

    gboolean
    modulemd_hash_table_equals (GHashTable *a,
                                GHashTable *b,
                                GEqualFunc compare_func);

#### Parameters

a | A GHashTable object. |
b | A GHashTable object. |
compare_func | A GEqualFunc function that is called to determine the equivalence of pairs of GHashTable values. |

#### Returns

TRUE if both `a` and `b` contain identical keys and identical corresponding values (as determined by `compare_func` ), FALSE if they differ.

Since: 2.2

### modulemd_hash_table_compare ()

    gint
    modulemd_hash_table_compare (GHashTable *a,
                                 GHashTable *b,
                                 GCompareFunc value_compare_func);

### modulemd_strcmp_sort ()

    gint
    modulemd_strcmp_sort (gconstpointer a,
                          gconstpointer b);

#### Parameters

a | A gconstpointer. |
b | A gconstpointer. |

#### Returns

0 if `a` and `b` are pointers to identical strings, a negative value if `a` is less than `b` , and a positive value if `a` is greater than `b` .

Since: 2.0

### modulemd_strcmp_wrapper ()

    gint
    modulemd_strcmp_wrapper (gconstpointer a,
                             gconstpointer b);

#### Parameters

a | A gconstpointer. | [in]
b | A gconstpointer. | [in]

#### Returns

0 if `a` and `b` are identical strings, a negative value if `a` is less than `b` , and a positive value if `a` is greater than `b` .

Since: 2.10

### modulemd_ordered_str_keys ()

    GPtrArray *
    modulemd_ordered_str_keys (GHashTable *htable,
                               GCompareFunc compare_func);

#### Parameters

htable | A GHashTable. |
compare_func | A GCompareFunc function that is called to determine the equivalence of pairs of GHashTable keys from `htable` . This should almost always be passed as `modulemd_strcmp_sort()`. |

#### Returns

A GPtrArray of the keys from `htable` sorted according to `compare_func` .

[transfer container]

Since: 2.0

### modulemd_ordered_str_keys_as_strv ()

    GStrv
    modulemd_ordered_str_keys_as_strv (GHashTable *htable);

#### Parameters

htable | A GHashTable. |

#### Returns

A GStrv list of the keys from `htable` sorted according to `modulemd_strcmp_sort()`.

[transfer full]

Since: 2.0

### modulemd_variant_deep_copy ()

    GVariant *
    modulemd_variant_deep_copy (GVariant *variant);

#### Parameters

variant | A GVariant opaque data structure. |

#### Returns

A newly-allocated deep copy of `variant` .

[transfer full]

Since: 2.0

### modulemd_hash_table_unref ()

    void
    modulemd_hash_table_unref (void *table);

Decrements the reference count of `table` (considered as a GHashTable). If the reference count drops to 0, all keys, values, and memory associated with `table` will be released.

The main purpose of this function is to provide a `GDestroyNotify()` function for GPtrArray, GHashTable, and similar object types.

#### Parameters

table | A void pointer. | [nullable]

Since: 2.0

### modulemd_validate_nevra ()

    gboolean
    modulemd_validate_nevra (const gchar *nevra);

#### Parameters

nevra | A NEVRA (Name, Epoch, Version, Release, Architecture) string. |

#### Returns

TRUE if `nevra` is in proper N-E:V-R.A format, FALSE otherwise.

Since: 2.0

### modulemd_boolean_equals ()

    gboolean
    modulemd_boolean_equals (gboolean a,
                             gboolean b);

Since a gboolean could contain any value represented by a gint, `a` and `b` are compared for logical equivalence.

#### Parameters

a | A gboolean value. |
b | A gboolean value. |

#### Returns

TRUE if `a` and `b` are logically equal, FALSE otherwise.

Since: 2.7

### modulemd_is_glob_pattern ()

    gboolean
    modulemd_is_glob_pattern (const char *pattern);

#### Parameters

pattern | (nullable) A string to check for glob patterns as defined by [glob(7)[(https://www.mankier.com/7/glob) |

#### Returns

TRUE if `pattern` contains any globbing characters. FALSE otherwise.

Since: 2.9

### compare_streams ()

    gint
    compare_streams (gconstpointer a,
                     gconstpointer b);

Sorting function for GPtrArrays of ModulemdModuleStream objects.

#### Parameters

a | The first ModulemdModuleStream to sort |
b | The second ModulemdModuleStream to sort |

Since: 2.9

### modulemd_fnmatch ()

    gboolean
    modulemd_fnmatch (const gchar *pattern,
                      const gchar *string);

A wrapper around `fnmatch()` for use with modulemd.

#### Parameters

pattern | (nullable) A string to check for glob patterns as defined by [glob(7)[(https://www.mankier.com/7/glob) |
string | (nullable) A string to check for matches. |

#### Returns

TRUE if `pattern` matched for this string or if `pattern` is NULL. FALSE if `pattern` did not match or `string` is NULL.

### modulemd_rpm_match ()

    gboolean
    modulemd_rpm_match (gpointer key);

This is a GHRFunc for use with `g_hash_table_find()` to search for RPMs. It is a wrapper around `modulemd_fnmatch()`.

#### Parameters

key | The key in the RPM artifacts hash table. |
value | The value in the RPM artifacts hash table (should be the same as `key` ). |
user_data | A glob pattern to match against the NEVRA strings of the RPM artifacts in `self` . |

#### Returns

TRUE if `key` is a match for the pattern in `user_data` .

### modulemd_iso8601date_to_guint64 ()

    guint64
    modulemd_iso8601date_to_guint64 (const gchar *iso8601);

#### Parameters

iso8601 | string containing a date in ISO 8601 format. | [in]

#### Returns

date represented as a 64-bit integer (such as 201807011200).

Since: 2.10

### modulemd_guint64_to_iso8601date ()

    gchar *
    modulemd_guint64_to_iso8601date (guint64 date);

#### Parameters

date | date represented as a 64-bit integer (such as 201807011200). | [in]

#### Returns

A newly-allocated string containing a date in ISO 8601 format.

[transfer full]

Since: 2.10

### MODULEMD_REPLACE_SET()

    #define             MODULEMD_REPLACE_SET(_dest, _set)

Frees the existing GHashTable at `_dest` . If `_set` is not NULL, assigns a deep copy of `_set` 's keys for use as a set.

This helper function is intended for use in `GOBJECT_copy()` functions to simplify copying internal set variables and avoid code duplication.

#### Parameters

_dest | A reference to a GHashTable. |
_set | A reference to a GHashTable. | [nullable]

Since: 2.0

### MODULEMD_SETTER_GETTER_STRING_EXT()

    #define             MODULEMD_SETTER_GETTER_STRING_EXT(                                    \
                  is_static, ObjName, obj_name, OBJ_NAME, attr, ATTR)

A convenience macro for defining standard set and get methods for a string attribute of an object.

This is the internal implementation for `MODULEMD_SETTER_GETTER_STRING` and `MODULEMD_SETTER_GETTER_STRING_STATIC` which should be used instead.

#### Parameters

is_static | static for private methods, or empty comment for public. |
ObjName | The name of the object type, in camel case. |
obj_name | The name of the object type, in lowercase with words separated by '_'. |
OBJ_NAME | The name of the object type, in uppercase with words separated by '_'. |
attr | The name of the object attribute, in lowercase. |
ATTR | The name of the object attribute, in uppercase. |

Since: 2.2

### MODULEMD_SETTER_GETTER_STRING()

    #define             MODULEMD_SETTER_GETTER_STRING(                                        \
                  ObjName, obj_name, OBJ_NAME, attr, ATTR)

A convenience macro for defining standard public set and get methods for a string attribute of an object.

#### Parameters

ObjName | The name of the object type, in camel case. |
obj_name | The name of the object type, in lowercase with words separated by '_'. |
OBJ_NAME | The name of the object type, in uppercase with words separated by '_'. |
attr | The name of the object attribute, in lowercase. |
ATTR | The name of the object attribute, in uppercase. |

Since: 2.2

### MODULEMD_SETTER_GETTER_STRING_STATIC()

    #define             MODULEMD_SETTER_GETTER_STRING_STATIC(                                 \
                  ObjName, obj_name, OBJ_NAME, attr, ATTR)

A is a convenience macro for defining standard private (static) set and get methods for a string attribute of an object.

#### Parameters

ObjName | The name of the object type, in camel case. |
obj_name | The name of the object type, in lowercase with words separated by '_'. |
OBJ_NAME | The name of the object type, in uppercase with words separated by '_'. |
attr | The name of the object attribute, in lowercase. |
ATTR | The name of the object attribute, in uppercase. |

Since: 2.2

### modulemd_str_set_new

    #define             modulemd_str_set_new()

A convenience macro to simplify the common operation of setting up a hash table in libmodulemd for containing a `set()` of unique strings.

Since: 2.10

## Types and Values

### FALLTHROUGH

    #define FALLTHROUGH __attribute__ ((fallthrough));