## Common Libfm utilities.

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

## Functions

const char * | (*FmAppCommandParseCallback) ()
int | fm_app_command_parse ()
char * | fm_file_size_to_str ()
char * | fm_file_size_to_str2 ()
gboolean | fm_key_file_get_int ()
gboolean | fm_key_file_get_bool ()
char * | fm_canonicalize_filename ()
char * | fm_strdup_replace ()
gboolean | fm_run_in_default_main_context ()
const char * | fm_get_home_dir ()
char * | fm_uri_subpath_to_native_subpath ()
void | fm_strcatv ()

## Types and Values

struct | FmAppCommandParseOption

## Description

`include` : libfm/fm.h

This scope contains common data parsing utilities.

## Functions

### FmAppCommandParseCallback ()

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

The handler which converts key char into string representation.

See also: `fm_app_command_parse()`.

#### Parameters

opt | key character |
user_data | data passed from caller of `fm_app_command_parse()` |

#### Returns

string representation.

Since: 1.0.0

### 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.

#### Parameters

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_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.

#### Parameters

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

#### Parameters

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_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.

#### Parameters

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_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.

#### Parameters

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_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.

#### Parameters

filename | a filename |
cwd | current work directory path |

#### Returns

a canonical name.

[transfer full]

Since: 0.1.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.

#### Parameters

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_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` .

#### Parameters

func | function to run |
data | data supplied for `func` |

#### Returns

output of `func` .

Since: 1.0.2

### 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_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.

#### Parameters

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

### fm_strcatv ()

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

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

#### Parameters

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

Since: 1.2.0

## Types and Values

### struct FmAppCommandParseOption

    struct FmAppCommandParseOption {
        char opt;
        FmAppCommandParseCallback callback;
    };

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

#### Members

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