## String Utility Functions

String Utility Functions — String utility functions provided by libglabels

## Synopsis

    #include <libglabels/lgl-str.h>

    gint                lgl_str_utf8_casecmp                (const gchar *s1,
                                                             const gchar *s2);
    gint                lgl_str_part_name_cmp               (const gchar *s1,
                                                             const gchar *s2);
    gchar *             lgl_str_format_fraction             (gdouble x);

## Description

This section defines string utility functions used by libglabels and of possible use to a user of libglabels.

## Details

### lgl_str_utf8_casecmp ()

    gint                lgl_str_utf8_casecmp                (const gchar *s1,
                                                             const gchar *s2);

Compare two UTF-8 strings, ignoring the case of characters.

This function should be used only on strings that are known to be encoded in UTF-8 or a compatible UTF-8 subset.

`s1` : | string to compare with s2.
`s2` : | string to compare with s1.
Returns : | 0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

### lgl_str_part_name_cmp ()

    gint                lgl_str_part_name_cmp               (const gchar *s1,
                                                             const gchar *s2);

Compare two UTF-8 strings representing part names or numbers. This function uses a natural sort order:

- Ignores case.

- Strings are divided into chunks (numeric and non-numeric)

- Non-numeric chunks are compared character by character

- Numerical chunks are compared numerically, so that "20" precedes "100".

- Comparison of chunks is performed left to right until the first difference is encountered or all chunks evaluate as equal.

This function should be used only on strings that are known to be encoded in UTF-8 or a compatible UTF-8 subset.

Numeric chunks are converted to 64 bit unsigned integers for comparison, so the behaviour may be unpredictable for numeric chunks that exceed 18446744073709551615.

`s1` : | string to compare with s2.
`s2` : | string to compare with s1.
Returns : | 0 if the strings match, a negative value if s1 < s2, or a positive value if s1 > s2.

### lgl_str_format_fraction ()

    gchar *             lgl_str_format_fraction             (gdouble x);

Create fractional representation of number, if possible. Uses UTF-8 superscripts and subscripts for numerator and denominator values respecively.

`x` : | Floating point number to convert to fractional notation
Returns : | UTF-8 string containing fractional representation of x.