## BUtils

BUtils — a collection of utility functions, mainly used from parsers

## Synopsis

    gchar*      b_filename_from_utf8            (const gchar *name,
                                                 const gchar *root,
                                                 GError **error);
    gboolean    b_parse_int                     (const gchar *str,
                                                 gint *value);
    gboolean    b_parse_boolean                 (const gchar *str,
                                                 gboolean *value);
    gboolean    b_parse_double                  (const gchar *str,
                                                 gdouble *value);
    gboolean    b_parse_coordinates             (const gchar **names,
                                                 const gchar **values,
                                                 gint *x,
                                                 gint *y);
    gboolean    b_parse_rectangle               (const gchar **names,
                                                 const gchar **values,
                                                 BRectangle *rect);
    gboolean    b_parse_color                   (const gchar **names,
                                                 const gchar **values,
                                                 BColor *color);
    gboolean    b_parse_param                   (GObject *object,
                                                 const gchar *root,
                                                 const gchar **names,
                                                 const gchar **values,
                                                 GError **error);
    gboolean    b_object_set_property           (GObject *object,
                                                 const gchar *key,
                                                 const gchar *value,
                                                 const gchar *root,
                                                 GError **error);

## Description

## Details

### b_filename_from_utf8 ()

    gchar*      b_filename_from_utf8            (const gchar *name,
                                                 const gchar *root,
                                                 GError **error);

Convert `name` in UTF-8 encoding to a filename in the filesystem's encoding. If `root` is non-`NULL` and `name` is not an absolute filename, the returned filename is built using `root` as a prefix.

`name` : | the filename in UTF-8 encoding
`root` : | an optional path to use
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | a pointer to the newly allocated filename or `NULL` in case of an error. This value must be freed with g_free().

### b_parse_int ()

    gboolean    b_parse_int                     (const gchar *str,
                                                 gint *value);

Parse an integer value from a string.

`str` : | the string to parse
`value` : | location to store the integer value
Returns : | `TRUE` if the string could be parsed, `FALSE` otherwise

### b_parse_boolean ()

    gboolean    b_parse_boolean                 (const gchar *str,
                                                 gboolean *value);

Parse a boolean value from a string.

`str` : | the string to parse
`value` : | location to store the boolean value
Returns : | `TRUE` if the string could be parsed, `FALSE` otherwise

### b_parse_double ()

    gboolean    b_parse_double                  (const gchar *str,
                                                 gdouble *value);

Parse a double (floating-point) value from a string.

`str` : | the string to parse
`value` : | location to store the double value
Returns : | `TRUE` if the string could be parsed, `FALSE` otherwise

### b_parse_coordinates ()

    gboolean    b_parse_coordinates             (const gchar **names,
                                                 const gchar **values,
                                                 gint *x,
                                                 gint *y);

Parses a pair of name/value arrays looking for the names "x" and "y" and tries to parse the associated values into integer values.

`names` : | a `NULL`-terminated array of names
`values` : | a `NULL`-terminated array of values
`x` : | location to store the value of the x coordinate
`y` : | location to store the value of the y coordinate
Returns : | `TRUE` if both coordinates could be parsed, `FALSE` otherwise

### b_parse_rectangle ()

    gboolean    b_parse_rectangle               (const gchar **names,
                                                 const gchar **values,
                                                 BRectangle *rect);

Parses a pair of name/value arrays looking for the names "x", "y", "width" and "heigth" and tries to parse the associated values into a BRectangle.

`names` : | a `NULL`-terminated array of names
`values` : | a `NULL`-terminated array of values
`rect` : | pointer to a BRectangle to store the result
Returns : | `TRUE` if the rectangle could be parsed, `FALSE` otherwise

### b_parse_color ()

    gboolean    b_parse_color                   (const gchar **names,
                                                 const gchar **values,
                                                 BColor *color);

Parses a pair of name/value arrays looking for the name "color" and tries to convert the associated value to a BColor. The color value is expected to be in hexadecimal notation as in HTML.

`names` : | a `NULL`-terminated array of names
`values` : | a `NULL`-terminated array of values
`color` : | pointer to a BColor to store the result
Returns : | `TRUE` if the color could be parsed, `FALSE` otherwise

### b_parse_param ()

    gboolean    b_parse_param                   (GObject *object,
                                                 const gchar *root,
                                                 const gchar **names,
                                                 const gchar **values,
                                                 GError **error);

Parses a pair of name/value arrays looking for the names "key" and "value". The key/value pair is then used to set the respective object property by calling b_object_set_property().

`object` : | a GObject
`root` : | an optional string to use as root if a filename is set
`names` : | a `NULL`-terminated array of names
`values` : | a `NULL`-terminated array of values
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` if parsing was successful, `FALSE` otherwise

### b_object_set_property ()

    gboolean    b_object_set_property           (GObject *object,
                                                 const gchar *key,
                                                 const gchar *value,
                                                 const gchar *root,
                                                 GError **error);

Sets the object property `key` by interpreting the string `value`. This function takes care of converting the string to the proper type. If the property is a `B_TYPE_FILENAME` the filename is build using the `root` parameter.

`object` : | a GObject
`key` : | the name of the property
`value` : | the property value as a string
`root` : | an optional string to use as root if a filename property is set
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` on success, `FALSE` otherwise