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

## Stability Level

Stable, unless otherwise indicated

## Functions

gchar * | as_markup_convert_simple ()
gboolean | as_utils_is_stock_icon_name ()
gboolean | as_utils_is_spdx_license_id ()
gboolean | as_utils_is_spdx_license ()
gboolean | as_utils_is_environment_id ()
gboolean | as_utils_is_category_id ()
gboolean | as_utils_is_blacklisted_id ()
gchar ** | as_utils_spdx_license_tokenize ()
gchar * | as_utils_spdx_license_detokenize ()
gboolean | as_utils_check_url_exists ()
gchar * | as_utils_find_icon_filename ()
gchar * | as_utils_find_icon_filename_full ()
gchar * | as_utils_get_string_overlap ()

## Types and Values

enum | AsUtilsFindIconFlag

## Includes

    #include <appstream-glib.h>

## Description

These functions are used internally to libappstream-glib, and some may be useful to user-applications.

## Functions

### as_markup_convert_simple ()

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

Converts an XML description into a printable form.

#### Parameters

markup | the text to copy. |
markup_len | the length of `markup` , or -1 if `markup` is NULL terminated. |
error | A GError or `NULL` |

#### Returns

a newly allocated `NULL` terminated string.

[transfer full]

Since 0.1.0

### as_utils_is_stock_icon_name ()

    gboolean
    as_utils_is_stock_icon_name (const gchar *name);

Searches the known list of stock icons.

#### Parameters

name | an icon name |

#### Returns

`TRUE` if the icon is a "stock icon name" and does not need to be included in the AppStream icon tarball

Since 0.1.3

### as_utils_is_spdx_license_id ()

    gboolean
    as_utils_is_spdx_license_id (const gchar *license_id);

Searches the known list of SPDX license IDs.

#### Parameters

license_id | a single SPDX license ID, e.g. "CC-BY-3.0" |

#### Returns

`TRUE` if the icon is a valid "SPDX license ID"

Since 0.1.5

### as_utils_is_spdx_license ()

    gboolean
    as_utils_is_spdx_license (const gchar *license);

Checks the licence string to check it being a valid licence. NOTE: SPDX licences can't typically contain brackets.

#### Parameters

license | a SPDX license string, e.g. "CC-BY-3.0 and GFDL-1.3" |

#### Returns

`TRUE` if the icon is a valid "SPDX license"

Since 0.2.5

### as_utils_is_environment_id ()

    gboolean
    as_utils_is_environment_id (const gchar *environment_id);

Searches the known list of registered environment IDs.

#### Parameters

environment_id | a desktop ID, e.g. "GNOME" |

#### Returns

`TRUE` if the environment ID is valid

Since 0.2.4

### as_utils_is_category_id ()

    gboolean
    as_utils_is_category_id (const gchar *category_id);

Searches the known list of registered category IDs.

#### Parameters

category_id | a desktop ID, e.g. "AudioVideoEditing" |

#### Returns

`TRUE` if the category ID is valid

Since 0.2.4

### as_utils_is_blacklisted_id ()

    gboolean
    as_utils_is_blacklisted_id (const gchar *desktop_id);

Searches the known list of blacklisted desktop IDs.

#### Parameters

desktop_id | a desktop ID, e.g. "gimp.desktop" |

#### Returns

`TRUE` if the desktop ID is blacklisted

Since 0.2.2

### as_utils_spdx_license_tokenize ()

    gchar **
    as_utils_spdx_license_tokenize (const gchar *license);

Tokenizes the SPDX license string (or any simarly formatted string) into parts. Any licence parts of the string e.g. "LGPL-2.0+" are prefexed with "@", the conjunctive replaced with "&" and the disjunctive replaced with "|". Brackets are added as indervidual tokens and other strings are appended into single tokens where possible.

#### Parameters

license | a license string, e.g. "LGPLv2+ and (QPL or GPLv2) and MIT" |

#### Returns

array of strings.

[transfer full]

Since 0.1.5

### as_utils_spdx_license_detokenize ()

    gchar *
    as_utils_spdx_license_detokenize (gchar **license_tokens);

De-tokenizes the SPDX licenses into a string.

#### Parameters

license_tokens | license tokens, typically from `as_utils_spdx_license_tokenize()` |

#### Returns

string.

[transfer full]

Since 0.2.5

### as_utils_check_url_exists ()

    gboolean
    as_utils_check_url_exists (const gchar *url,
                               guint timeout,
                               GError **error);

Checks to see if a URL is reachable.

#### Parameters

url | the URL to check. |
timeout | the timeout in seconds. |
error | A GError or `NULL` |

#### Returns

`TRUE` if the URL was reachable and pointed to a non-zero-length file.

Since 0.1.5

### as_utils_find_icon_filename ()

    gchar *
    as_utils_find_icon_filename (const gchar *destdir,
                                 const gchar *search,
                                 GError **error);

Finds an icon filename from a filesystem root.

#### Parameters

destdir | the destdir. |
search | the icon search name, e.g. "microphone.svg" |
error | A GError or `NULL` |

#### Returns

a newly allocated `NULL` terminated string.

[transfer full]

Since 0.2.5

### as_utils_find_icon_filename_full ()

    gchar *
    as_utils_find_icon_filename_full (const gchar *destdir,
                                      const gchar *search,
                                      AsUtilsFindIconFlag flags,
                                      GError **error);

Finds an icon filename from a filesystem root.

#### Parameters

destdir | the destdir. |
search | the icon search name, e.g. "microphone.svg" |
flags | A AsUtilsFindIconFlag bitfield |
error | A GError or `NULL` |

#### Returns

a newly allocated `NULL` terminated string.

[transfer full]

Since 0.3.1

### as_utils_get_string_overlap ()

    gchar *
    as_utils_get_string_overlap (const gchar *s1,
                                 const gchar *s2);

Return a prefix and sufffix that is common to both strings.

#### Parameters

s1 | A string. |
s2 | Another string |

#### Returns

a newly allocated `NULL` terminated string, or `NULL`.

[transfer full]

Since 0.3.1

## Types and Values

### enum AsUtilsFindIconFlag

The flags used when finding icons.

#### Members

AS_UTILS_FIND_ICON_NONE | No flags set |
AS_UTILS_FIND_ICON_HI_DPI | Prefer a HiDPI icon |