## fm-path

fm-path

## Synopsis

    #define             FM_PATH                             (path)
    struct              FmPath;
    typedef             FmPathList;
    gboolean            fm_list_is_path_list                (FmList *list);
    int                 fm_path_depth                       (FmPath *path);
    char *              fm_path_display_basename            (FmPath *path);
    char *              fm_path_display_name                (FmPath *path,
                                                             gboolean human_readable);
    gboolean            fm_path_equal                       (FmPath *p1,
                                                             FmPath *p2);
    gboolean            fm_path_equal_str                   (FmPath *path,
                                                             const gchar *str,
                                                             int n);
    FmPath *            fm_path_get_apps_menu               ();
    const char *        fm_path_get_basename                (FmPath *path);
    FmPath *            fm_path_get_desktop                 ();
    FmPathFlags         fm_path_get_flags                   (FmPath *path);
    FmPath *            fm_path_get_home                    ();
    FmPath *            fm_path_get_parent                  (FmPath *path);
    FmPath *            fm_path_get_root                    ();
    FmPath *            fm_path_get_trash                   ();
    gboolean            fm_path_has_prefix                  (FmPath *path,
                                                             FmPath *prefix);
    guint               fm_path_hash                        (FmPath *path);
    #define             fm_path_is_local                    (path)
    #define             fm_path_is_native                   (path)
    #define             fm_path_is_trash                    (path)
    #define             fm_path_is_trash_root               (path)
    #define             fm_path_is_virtual                  (path)
    #define             fm_path_is_xdg_menu                 (path)
    FmPathList *        fm_path_list_new                    ();
    FmPathList *        fm_path_list_new_from_file_info_glist
                                                            (GList *fis);
    FmPathList *        fm_path_list_new_from_file_info_gslist
                                                            (GSList *fis);
    FmPathList *        fm_path_list_new_from_file_info_list
                                                            (FmList *fis);
    FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);
    FmPathList *        fm_path_list_new_from_uris          (const char **uris);
    char *              fm_path_list_to_uri_list            (FmPathList *pl);
    void                fm_path_list_write_uri_list         (FmPathList *pl,
                                                             GString *buf);
    #define             fm_path_new                         (path)
    FmPath *            fm_path_new_child                   (FmPath *parent,
                                                             const char *basename);
    FmPath *            fm_path_new_child_len               (FmPath *parent,
                                                             const char *basename,
                                                             int name_len);
    FmPath *            fm_path_new_for_commandline_arg     (const char *arg);
    FmPath *            fm_path_new_for_display_name        (const char *path_name);
    FmPath *            fm_path_new_for_gfile               (GFile *gf);
    FmPath *            fm_path_new_for_path                (const char *path_name);
    FmPath *            fm_path_new_for_str                 (const char *path_str);
    FmPath *            fm_path_new_for_uri                 (const char *uri);
    FmPath *            fm_path_new_relative                (FmPath *parent,
                                                             const char *relative_path);
    FmPath *            fm_path_ref                         (FmPath *path);
    GFile *             fm_path_to_gfile                    (FmPath *path);
    char *              fm_path_to_str                      (FmPath *path);
    char *              fm_path_to_uri                      (FmPath *path);
    void                fm_path_unref                       (FmPath *path);

## Description

## Details

### FM_PATH()

    #define FM_PATH(path)   ((FmPath*)path)

### struct FmPath

    struct FmPath {
        gint n_ref;
        FmPath* parent;
        guchar flags; /* FmPathFlags flags : 8; */
        char name[1];
    };

### FmPathList

    typedef FmList FmPathList;

### fm_list_is_path_list ()

    gboolean            fm_list_is_path_list                (FmList *list);

### fm_path_depth ()

    int                 fm_path_depth                       (FmPath *path);

### fm_path_display_basename ()

    char *              fm_path_display_basename            (FmPath *path);

### fm_path_display_name ()

    char *              fm_path_display_name                (FmPath *path,
                                                             gboolean human_readable);

### fm_path_equal ()

    gboolean            fm_path_equal                       (FmPath *p1,
                                                             FmPath *p2);

### fm_path_equal_str ()

    gboolean            fm_path_equal_str                   (FmPath *path,
                                                             const gchar *str,
                                                             int n);

### fm_path_get_apps_menu ()

    FmPath *            fm_path_get_apps_menu               ();

### fm_path_get_basename ()

    const char *        fm_path_get_basename                (FmPath *path);

### fm_path_get_desktop ()

    FmPath *            fm_path_get_desktop                 ();

### fm_path_get_flags ()

    FmPathFlags         fm_path_get_flags                   (FmPath *path);

### fm_path_get_home ()

    FmPath *            fm_path_get_home                    ();

### fm_path_get_parent ()

    FmPath *            fm_path_get_parent                  (FmPath *path);

### fm_path_get_root ()

    FmPath *            fm_path_get_root                    ();

### fm_path_get_trash ()

    FmPath *            fm_path_get_trash                   ();

### fm_path_has_prefix ()

    gboolean            fm_path_has_prefix                  (FmPath *path,
                                                             FmPath *prefix);

Check if `prefix` is a prefix of `path`. For example: /usr/share is the prefix of /usr/share/docs/libfm but /etc is not.

`path` : | a sub path
`prefix` : | a prefix
Returns : | TRUE if `prefix` is the prefix of `path`.

### fm_path_hash ()

    guint               fm_path_hash                        (FmPath *path);

### fm_path_is_local()

    #define fm_path_is_local(path) (fm_path_get_flags(path)&FM_PATH_IS_LOCAL)

### fm_path_is_native()

    #define fm_path_is_native(path) (fm_path_get_flags(path)&FM_PATH_IS_NATIVE)

### fm_path_is_trash()

    #define fm_path_is_trash(path) (fm_path_get_flags(path)&FM_PATH_IS_TRASH)

### fm_path_is_trash_root()

    #define fm_path_is_trash_root(path) (path == fm_path_get_trash())

### fm_path_is_virtual()

    #define fm_path_is_virtual(path) (fm_path_get_flags(path)&FM_PATH_IS_VIRTUAL)

### fm_path_is_xdg_menu()

    #define fm_path_is_xdg_menu(path) (fm_path_get_flags(path)&FM_PATH_IS_XDG_MENU)

### fm_path_list_new ()

    FmPathList *        fm_path_list_new                    ();

### fm_path_list_new_from_file_info_glist ()

    FmPathList *        fm_path_list_new_from_file_info_glist
                                                            (GList *fis);

### fm_path_list_new_from_file_info_gslist ()

    FmPathList *        fm_path_list_new_from_file_info_gslist
                                                            (GSList *fis);

### fm_path_list_new_from_file_info_list ()

    FmPathList *        fm_path_list_new_from_file_info_list
                                                            (FmList *fis);

### fm_path_list_new_from_uri_list ()

    FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);

### fm_path_list_new_from_uris ()

    FmPathList *        fm_path_list_new_from_uris          (const char **uris);

### fm_path_list_to_uri_list ()

    char *              fm_path_list_to_uri_list            (FmPathList *pl);

### fm_path_list_write_uri_list ()

    void                fm_path_list_write_uri_list         (FmPathList *pl,
                                                             GString *buf);

### fm_path_new()

    #define fm_path_new(path)   fm_path_new_for_str(path)

### fm_path_new_child ()

    FmPath *            fm_path_new_child                   (FmPath *parent,
                                                             const char *basename);

`parent` : | a parent path
`basename` : | basename of a direct child of `parent` directory in glib filename encoding. (can be non-UTF-8).
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_child_len ()

    FmPath *            fm_path_new_child_len               (FmPath *parent,
                                                             const char *basename,
                                                             int name_len);

`parent` : | a parent path
`basename` : | basename of a direct child of `parent` directory in glib filename encoding. (can be non-UTF-8).
`len` : | length of basename
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_commandline_arg ()

    FmPath *            fm_path_new_for_commandline_arg     (const char *arg);

`arg` : | a file path passed in command line argv to the program. The `arg` can be a POSIX path in glib filename encoding (can be non-UTTF-8) and can be a URI with non-ASCII characters escaped, like http://wiki.lxde.org/zh/`E9`%A6`96`%E9`A0`%81.
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_display_name ()

    FmPath *            fm_path_new_for_display_name        (const char *path_name);

You can call `fm_path_display_name()` to convert a FmPath to a UTF-8 encoded name ready for being displayed in the GUI.

`path_name` : | a UTF-8 encoded display name for the path It can either be a POSIX path in UTF-8 encoding, or an unescaped URI (can contain non-ASCII characters and spaces)
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_gfile ()

    FmPath *            fm_path_new_for_gfile               (GFile *gf);

This function converts a GFile object to FmPath.

`gf` : | a GFile object
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_path ()

    FmPath *            fm_path_new_for_path                (const char *path_name);

`path_name` : | a POSIX path.
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_str ()

    FmPath *            fm_path_new_for_str                 (const char *path_str);

You can call `fm_path_to_str()` to convert a FmPath back to its string presentation.

`path_str` : | a string representing the file path in its native encoding (can be non-UTF-8). It can either be a native path or an unescaped URI (can contain non-ASCII characters and spaces). The function will try to figure out what to do.
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_for_uri ()

    FmPath *            fm_path_new_for_uri                 (const char *uri);

You can call `fm_path_to_uri()` to convert a FmPath to a escaped URI string.

`path_name` : | a URI with special characters escaped. Encoded URI such as http://wiki.lxde.org/zh/`E9`%A6`96`%E9`A0`%81 will be unescaped.
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_new_relative ()

    FmPath *            fm_path_new_relative                (FmPath *parent,
                                                             const char *relative_path);

For example, if `parent` is "http://wiki.lxde.org/" and `rel` is "zh/`E9`%A6`96`%E9`A0`%81", you have to unescape the relative path prior to passing it to `fm_path_new_relative()`.

If `parent` is NULL, this works the same as fm_path_new_for_str(`rel`)

`parent` : | a parent path
`rel` : | a path relative to `parent` in glib filename encoding. (can be non-UTF-8). However this should not be a escaped ASCII string used in URI. If you're building a relative path for a URI, and the relative path is escaped, you have to unescape it first.
Returns : | a newly created FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed.

### fm_path_ref ()

    FmPath *            fm_path_ref                         (FmPath *path);

### fm_path_to_gfile ()

    GFile *             fm_path_to_gfile                    (FmPath *path);

### fm_path_to_str ()

    char *              fm_path_to_str                      (FmPath *path);

### fm_path_to_uri ()

    char *              fm_path_to_uri                      (FmPath *path);

### fm_path_unref ()

    void                fm_path_unref                       (FmPath *path);