Common Libfm utilities.

## Common Libfm utilities. Common Libfm utilities. — Common utility functions used by libfm and libfm-gtk. |

## Synopsis

    const char *        (*FmAppCommandParseCallback)        (char opt,
                                                             gpointer user_data);
    struct              FmAppCommandParseOption;
    int                 fm_app_command_parse                (const char *cmd,
                                                             const FmAppCommandParseOption *opts,
                                                             char **ret,
                                                             gpointer user_data);
    char *              fm_canonicalize_filename            (const char *filename,
                                                             const char *cwd);
    char *              fm_file_size_to_str                 (char *buf,
                                                             size_t buf_size,
                                                             goffset size,
                                                             gboolean si_prefix);
    char *              fm_file_size_to_str2                (char *buf,
                                                             size_t buf_size,
                                                             goffset size,
                                                             char size_units);
    const char *        fm_get_home_dir                     (void);
    gboolean            fm_key_file_get_bool                (GKeyFile *kf,
                                                             const char *grp,
                                                             const char *key,
                                                             gboolean *val);
    gboolean            fm_key_file_get_int                 (GKeyFile *kf,
                                                             const char *grp,
                                                             const char *key,
                                                             int *val);
    gboolean            fm_run_in_default_main_context      (GSourceFunc func,
                                                             gpointer data);
    void                fm_strcatv                          (char ***strvp,
                                                             char * const *astrv);
    char *              fm_strdup_replace                   (char *str,
                                                             char *old_str,
                                                             char *new_str);
    char *              fm_uri_subpath_to_native_subpath    (const char *subpath,
                                                             GError **error);

## Description

`include`: libfm/fm.h

This scope contains common data parsing utilities.

## Details

### FmAppCommandParseCallback ()

    const char *        (*FmAppCommandParseCallback)        (char opt,
                                                             gpointer user_data);

The handler which converts key char into string representation.

See also: `fm_app_command_parse()`.

`opt` : | key character
`user_data` : | data passed from caller of `fm_app_command_parse()`
Returns : | string representation.

Since 1.0.0

### struct FmAppCommandParseOption

    struct FmAppCommandParseOption {
        char opt;
        FmAppCommandParseCallback callback;
    };

Element of correspondence for substitutions by `fm_app_command_parse()`.

char `opt`; | key character
FmAppCommandParseCallback `callback`; | subroutine to get string for substitution

### fm_app_command_parse ()

    int                 fm_app_command_parse                (const char *cmd,
                                                             const FmAppCommandParseOption *opts,
                                                             char **ret,
                                                             gpointer user_data);

This function parses line that contains some %<char> commands and does substitutions on them using callbacks provided by caller. Only options in `opts` and %% will be expanded, all other %<char> sequences will be skipped.

`cmd` : | line to parse
`opts` : | plain list of possible options
`ret` : | pointer for resulting string, string should be freed by caller. [out][transfer full]
`user_data` : | caller data to pass to callback
Returns : | number of valid options found in `cmd`.

Since 1.0.0

### fm_canonicalize_filename ()

    char *              fm_canonicalize_filename            (const char *filename,
                                                             const char *cwd);

Makes a canonical name with full path from `filename`. Returned string should be freed by caller after usage.

`filename` : | a filename
`cwd` : | current work directory path
Returns : | a canonical name. [transfer full]

Since 0.1.0

### fm_file_size_to_str ()

    char *              fm_file_size_to_str                 (char *buf,
                                                             size_t buf_size,
                                                             goffset size,
                                                             gboolean si_prefix);

Converts `size` into text representation of form "21.4 kiB" for example.

`buf` : | pointer to array to make a string
`buf_size` : | size of `buf`
`size` : | number to convert
`si_prefix` : | `TRUE` to convert in SI units, `FALSE` to convert in IEC units
Returns : | `buf`.

Since 0.1.0

### fm_file_size_to_str2 ()

    char *              fm_file_size_to_str2                (char *buf,
                                                             size_t buf_size,
                                                             goffset size,
                                                             char size_units);

Converts `size` into text representation of form "21.4 kiB" for example. The `size_units` defines which unit will be selected to convert (similar to ones that 'du' utility uses):

- b : bytes

- k : KiB (1024 bytes)

- m : MiB (1048576 bytes)

- g : GiB (1073741824 bytes)

- K : kB (1000 bytes)

- M : MB (1000000 bytes)

- G : GB (1000000000 bytes)

- h : adaptive in IEC units

- H : adaptive in SI units

`buf` : | pointer to array to make a string
`buf_size` : | size of `buf`
`size` : | number to convert
`size_units` : | type of units to convert
Returns : | `buf`.

Since 0.1.0

### fm_get_home_dir ()

    const char *        fm_get_home_dir                     (void);

Retrieves valid path to home dir of user.

Returns : | path string.

Since 1.0.2

### fm_key_file_get_bool ()

    gboolean            fm_key_file_get_bool                (GKeyFile *kf,
                                                             const char *grp,
                                                             const char *key,
                                                             gboolean *val);

Lookups `key` in `kf` and stores found value in `val` if the `key` was found.

`kf` : | a key file
`grp` : | group to lookup key
`key` : | a key to lookup
`val` : | location to store value
Returns : | `TRUE` if `key` was found.

Since 0.1.0

### fm_key_file_get_int ()

    gboolean            fm_key_file_get_int                 (GKeyFile *kf,
                                                             const char *grp,
                                                             const char *key,
                                                             int *val);

Lookups `key` in `kf` and stores found value in `val` if the `key` was found.

`kf` : | a key file
`grp` : | group to lookup key
`key` : | a key to lookup
`val` : | location to store value
Returns : | `TRUE` if `key` was found.

Since 0.1.0

### fm_run_in_default_main_context ()

    gboolean            fm_run_in_default_main_context      (GSourceFunc func,
                                                             gpointer data);

Runs `func` once in global main loop with supplied `data`.

`func` : | function to run
`data` : | data supplied for `func`
Returns : | output of `func`.

Since 1.0.2

### fm_strcatv ()

    void                fm_strcatv                          (char ***strvp,
                                                             char * const *astrv);

Appends string list `astrv` to `strvp` replacing it.

`strvp` : | pointer to strings list
`astrv` : | list of strings to append. [allow-none]

Since 1.2.0

### fm_strdup_replace ()

    char *              fm_strdup_replace                   (char *str,
                                                             char *old_str,
                                                             char *new_str);

Replaces every occurence of `old_str` in `str` with `new_str` and returns resulted string. Returned string should be freed with `g_free()` after usage.

Before 1.0.0 this API had name fm_str_replace.

`str` : | a string
`old_str` : | substring to replace
`new_str` : | string to replace `old_str`
Returns : | resulted string. [transfer full]

Since 0.1.16

### fm_uri_subpath_to_native_subpath ()

    char *              fm_uri_subpath_to_native_subpath    (const char *subpath,
                                                             GError **error);

Converts escaped URI subpath into file path in native encoding.

`subpath` : | URI substring to convert
`error` : | location to set error. [out][allow-none]
Returns : | transcoded path or `NULL` in case of error. [transfer full]

Since 1.2.0