as-utils: AppStream Library Reference Manual

## as-utils as-utils — Helper functions that are used inside libappstream |

## Functions

GQuark | as_utils_error_quark ()
gchar ** | as_markup_strsplit_words ()
gchar * | as_markup_convert_simple ()
gboolean | as_utils_locale_is_compatible ()
gchar * | as_utils_posix_locale_to_bcp47 ()
gboolean | as_utils_is_category_name ()
gboolean | as_utils_is_tld ()
gboolean | as_utils_is_desktop_environment ()
void | as_utils_sort_components_into_categories ()
gchar * | as_utils_build_data_id ()
gboolean | as_utils_data_id_valid ()
gchar * | as_utils_data_id_get_cid ()
gboolean | as_utils_data_id_match ()
gboolean | as_utils_data_id_equal ()
guint | as_utils_data_id_hash ()
guint | as_gstring_replace ()
guint | as_gstring_replace2 ()
gboolean | as_utils_is_platform_triplet ()
gboolean | as_utils_install_metadata_file ()
AsComponentScope | as_utils_guess_scope_from_path ()
const gchar * | as_get_appstream_version ()

## Types and Values

enum | AsUtilsError
#define | AS_UTILS_ERROR
enum | AsDataIdMatchFlags
enum | AsMetadataLocation

## Includes

    #include <appstream.h>

## Description

Functions which are used in libappstream and might be useful for others as well.

## Functions

### as_utils_error_quark ()

    GQuark
    as_utils_error_quark (void);

#### Returns

An error quark.

Since: 0.14.0

### as_markup_strsplit_words ()

    gchar **
    as_markup_strsplit_words (const gchar *text,
                              guint line_len);

Splits up a long line into an array of smaller strings, each being no longer than `line_len` . Words are not split.

#### Parameters

text | the text to split. |
line_len | the maximum length of the output line |

#### Returns

lines, or `NULL` in event of an error.

[transfer full]

Since: 0.14.0

### as_markup_convert_simple ()

    gchar *
    as_markup_convert_simple (const gchar *markup,
                              GError **error);

### as_utils_locale_is_compatible ()

    gboolean
    as_utils_locale_is_compatible (const gchar *locale1,
                                   const gchar *locale2);

Calculates if one locale is compatible with another. When doing the calculation the locale and language code is taken into account if possible.

#### Parameters

locale1 | a BCP47 or POSIX locale string, or `NULL`. | [nullable]
locale2 | a BCP47 or POSIX locale string, or `NULL`. | [nullable]

#### Returns

`TRUE` if the locale is compatible.

Since: 0.9.5

### as_utils_posix_locale_to_bcp47 ()

    gchar *
    as_utils_posix_locale_to_bcp47 (const gchar *locale);

Converts a POSIX locale string to the corresponding IETF BCP47 format. If the given locale is already in BCP47 format, no change will be done.

#### Returns

A locale string, free with `g_free()`.

[transfer full]

### as_utils_is_category_name ()

    gboolean
    as_utils_is_category_name (const gchar *category_name);

### as_utils_is_tld ()

    gboolean
    as_utils_is_tld (const gchar *tld);

Searches the known list of TLDs we allow for AppStream IDs. This excludes internationalized names.

#### Parameters

tld | a top-level domain without dot, e.g. "de", "org", "name" |

#### Returns

`TRUE` if the TLD is valid

Since: 0.9.8

### as_utils_is_desktop_environment ()

    gboolean
    as_utils_is_desktop_environment (const gchar *desktop);

Searches the known list of desktop environments AppStream knows about.

#### Parameters

desktop | a desktop environment id. |

#### Returns

`TRUE` if the desktop-id is valid

Since: 0.10.0

### as_utils_sort_components_into_categories ()

    void
    as_utils_sort_components_into_categories
                                   (GPtrArray *cpts,
                                    GPtrArray *categories,
                                    gboolean check_duplicates);

Sorts all components in `cpts` into the AsCategory categories listed in `categories` .

#### Parameters

cpts | List of components. | [element-type AsComponent]
categories | List of categories to sort components into. | [element-type AsCategory]
check_duplicates | Whether to check for duplicates. |

### as_utils_build_data_id ()

    gchar *
    as_utils_build_data_id (AsComponentScope scope,
                            AsBundleKind bundle_kind,
                            const gchar *origin,
                            const gchar *cid,
                            const gchar *branch);

Builds an identifier string unique to the individual dataset using the supplied information.

#### Parameters

scope | Scope of the metadata as AsComponentScope e.g. `AS_COMPONENT_SCOPE_SYSTEM` |
bundle_kind | Bundling system providing this data, e.g. 'package' or 'flatpak' |
origin | Origin string, e.g. 'os' or 'gnome-apps-nightly' |
cid | AppStream component ID, e.g. 'org.freedesktop.appstream.cli' |
branch | Branch, e.g. '3-20' or 'master' |

Since: 0.14.0

### as_utils_data_id_valid ()

    gboolean
    as_utils_data_id_valid (const gchar *data_id);

Checks if a data ID is valid i.e. has the correct number of sections.

#### Parameters

data_id | a component data ID |

#### Returns

`TRUE` if the ID is valid

Since: 0.14.0

### as_utils_data_id_get_cid ()

    gchar *
    as_utils_data_id_get_cid (const gchar *data_id);

Get the component-id part of the data-id.

#### Parameters

data_id | The data-id. |

### as_utils_data_id_match ()

    gboolean
    as_utils_data_id_match (const gchar *data_id1,
                            const gchar *data_id2,
                            AsDataIdMatchFlags match_flags);

Checks two data IDs for equality allowing globs to match, whilst also allowing clients to whitelist sections that have to match.

#### Parameters

data_id1 | a data ID |
data_id2 | another data ID |
match_flags | a AsDataIdMatchFlags bitfield, e.g. `AS_DATA_ID_MATCH_FLAG_ID` |

#### Returns

`TRUE` if the IDs should be considered equal.

Since: 0.14.0

### as_utils_data_id_equal ()

    gboolean
    as_utils_data_id_equal (const gchar *data_id1,
                            const gchar *data_id2);

Checks two component data IDs for equality allowing globs to match.

#### Parameters

data_id1 | a data ID |
data_id2 | another data ID |

#### Returns

`TRUE` if the ID's should be considered equal.

Since: 0.14.0

### as_utils_data_id_hash ()

    guint
    as_utils_data_id_hash (const gchar *data_id);

Converts a data-id to a hash value.

This function implements the widely used DJB hash on the ID subset of the data-id string.

It can be passed to `g_hash_table_new()` as the hash_func parameter, when using non-NULL strings or unique_ids as keys in a GHashTable.

#### Parameters

data_id | a data ID |

#### Returns

a hash value corresponding to the key

Since: 0.14.0

### as_gstring_replace ()

    guint
    as_gstring_replace (GString *string,
                        const gchar *find,
                        const gchar *replace);

Replaces all occurences of `find` with the string `replace` in a GString.

#### Parameters

string | a GString |
find | the string to find in `string` |
replace | the string to insert in place of `find` |

#### Returns

the number of find and replace operations performed.

### as_gstring_replace2 ()

    guint
    as_gstring_replace2 (GString *string,
                         const gchar *find,
                         const gchar *replace,
                         guint limit);

Replaces the string `find` with the string `replace` in a GString up to `limit` times. If the number of instances of `find` in the GString is less than `limit` , all instances are replaced. If `limit` is `0`, all instances of `find` are replaced.

#### Parameters

string | a GString |
find | the string to find in `string` |
replace | the string to insert in place of `find` |
limit | the maximum instances of `find` to replace with `replace` , or `0` for no limit |

#### Returns

the number of find and replace operations performed.

### as_utils_is_platform_triplet ()

    gboolean
    as_utils_is_platform_triplet (const gchar *triplet);

Test if the given string is a valid platform triplet recognized by AppStream.

#### Parameters

triplet | a platform triplet. |

#### Returns

`TRUE` if triplet is valid.

Since: 0.14.0

### as_utils_install_metadata_file ()

    gboolean
    as_utils_install_metadata_file (AsMetadataLocation location,
                                    const gchar *filename,
                                    const gchar *origin,
                                    const gchar *destdir,
                                    GError **error);

Installs an AppStream MetaInfo, AppStream Metadata Catalog or AppStream Icon tarball file to the right place on the filesystem. Please note that this function does almost no validation and may guess missing values such as icon sizes and origin names. Ensure your metadata is good before installing it.

#### Parameters

location | the AsMetadataLocation, e.g. `AS_METADATA_LOCATION_CACHE` |
filename | the full path of the file to install |
origin | the origin to use for the installation, or `NULL` |
destdir | the destdir to use, or `NULL` |
error | A GError or `NULL` |

#### Returns

`TRUE` for success, `FALSE` if error is set

Since: 0.14.0

### as_utils_guess_scope_from_path ()

    AsComponentScope
    as_utils_guess_scope_from_path (const gchar *path);

Guess the AsComponentScope that applies to a given path.

#### Parameters

path | The filename to test. |

#### Returns

the AsComponentScope

Since: 0.15.0

### as_get_appstream_version ()

    const gchar *
    as_get_appstream_version (void);

`as_get_appstream_version` is deprecated and should not be used in newly-written code.

Get the version of the AppStream library that is currently used as a string.

#### Returns

The AppStream version.

## Types and Values

### enum AsUtilsError

The error type.

#### Members

AS_UTILS_ERROR_FAILED | Generic failure |

### AS_UTILS_ERROR

    #define AS_UTILS_ERROR				as_utils_error_quark ()

### enum AsDataIdMatchFlags

The flags used when matching unique IDs.

#### Members

AS_DATA_ID_MATCH_FLAG_NONE | No flags set |
AS_DATA_ID_MATCH_FLAG_SCOPE | Scope, e.g. a AsComponentScope |
AS_DATA_ID_MATCH_FLAG_BUNDLE_KIND | Bundle kind, e.g. a AsBundleKind |
AS_DATA_ID_MATCH_FLAG_ORIGIN | Origin |
AS_DATA_ID_MATCH_FLAG_ID | Component AppStream ID |
AS_DATA_ID_MATCH_FLAG_BRANCH | Branch |

### enum AsMetadataLocation

The flags used when installing and removing metadata files.

#### Members

AS_METADATA_LOCATION_SHARED | Installed by the vendor, shared |
AS_METADATA_LOCATION_STATE | Installed as metadata into /var/lib, shared |
AS_METADATA_LOCATION_CACHE | Installed as metadata into /var/cache, shared |
AS_METADATA_LOCATION_USER | Installed for the current user |