FmPath

## FmPath FmPath — Path representation for libfm. |

## Synopsis

    #define             FM_PATH                             (path)
                        FmFileInfoList;
                        FmPath;
    enum                FmPathFlags;
                        FmPathList;
    int                 fm_path_compare                     (FmPath *p1,
                                                             FmPath *p2);
    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               (void);
    const char *        fm_path_get_basename                (FmPath *path);
    FmPath *            fm_path_get_desktop                 (void);
    FmPathFlags         fm_path_get_flags                   (FmPath *path);
    FmPath *            fm_path_get_home                    (void);
    FmPath *            fm_path_get_parent                  (FmPath *path);
    FmPath *            fm_path_get_root                    (void);
    FmPath *            fm_path_get_scheme_path             (FmPath *path);
    FmPath *            fm_path_get_trash                   (void);
    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_native_or_trash          (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                    (void);
    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
                                                            (FmFileInfoList *fis);
    FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);
    FmPathList *        fm_path_list_new_from_uris          (char * const*uris);
    char *              fm_path_list_to_uri_list            (FmPathList *pl);
    void                fm_path_list_write_uri_list         (FmPathList *pl,
                                                             GString *buf);
    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 *rel);
    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

`include`: libfm/fm.h

## Details

### FM_PATH()

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

### FmFileInfoList

    typedef struct _FmFileInfoList FmFileInfoList;

### FmPath

    typedef struct _FmPath FmPath;

### enum FmPathFlags

    typedef enum {
        FM_PATH_NONE = 0,
        FM_PATH_IS_NATIVE = 1<<0,
        FM_PATH_IS_LOCAL = 1<<1,
        FM_PATH_IS_VIRTUAL = 1<<2,
        FM_PATH_IS_TRASH = 1<<3,
        FM_PATH_IS_XDG_MENU = 1<<4,
    } FmPathFlags;

Flags of FmPath object.

FM_PATH_IS_VIRTUAL and FM_PATH_IS_XDG_MENU are deprecated since 1.0.2 and FM_PATH_IS_LOCAL is deprecated since 1.2.0, and should not be used in newly written code.

`FM_PATH_NONE` | -
`FM_PATH_IS_NATIVE` | This is a native path to UNIX, like /home
`FM_PATH_IS_LOCAL` | This path refers to a file on local filesystem
`FM_PATH_IS_VIRTUAL` | This path is virtual and it doesn't exist on real filesystem
`FM_PATH_IS_TRASH` | This path is under trash:///
`FM_PATH_IS_XDG_MENU` | This path is under menu:///

### FmPathList

    typedef struct _FmPathList FmPathList;

### fm_path_compare ()

    int                 fm_path_compare                     (FmPath *p1,
                                                             FmPath *p2);

### fm_path_depth ()

    int                 fm_path_depth                       (FmPath *path);

Calculates how many elements are in this path.

`path` : | a path
Returns : | `TRUE` if paths are equal.

Since 1.0.0

### fm_path_display_basename ()

    char *              fm_path_display_basename            (FmPath *path);

Creates displayable basename of `path`. If `path` is a scheme root path (i.e. "/", "sftp://", etc.) then returns basename of `path`. For other paths displayable basename may be reliable only if there was already FmFileInfo retrieved for the `path`, otherwise some estimation will be done instead, be careful with this API. Returned data should be freed with `g_free()` after usage.

See also: `fm_file_info_get_disp_name()`.

`path` : | a path
Returns : | displayable basename of path. [transfer full]

Since 0.1.0

### fm_path_display_name ()

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

Creates string representation of `path` as displayable UTF-8 string. The conversion is the most probably unreversible so returned value should be used only for displaying purposes. The displayable path may be reliable only if there was already FmFileInfo retrieved for the `path`, otherwise some estimation will be returned instead, be careful with this API. The main purpose for this API is to create displayable path for the path entry. Applications are encouraged to use `g_file_get_parse_name()` instead for any other purposes. Returned data should be freed with `g_free()` after usage.

See also: `fm_path_display_basename()`, `fm_path_to_str()`.

`path` : | a path
`human_readable` : | ignored since 1.2.0
Returns : | path string. [transfer full]

Since 0.1.0

### fm_path_equal ()

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

Compares two paths and returns `TRUE` if they are equal.

Note that this function is primarily meant as a hash table comparison function.

See also: `fm_path_compare()`.

`p1` : | first path
`p2` : | second path
Returns : | `TRUE` if paths are equal.

Since 0.1.0

### fm_path_equal_str ()

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

Compares path string representation with `string`.

`path` : | a path
`str` : | a string
`n` : | length of `string`
Returns : | `TRUE` if path and string are equal.

Since 0.1.0

### fm_path_get_apps_menu ()

    FmPath *            fm_path_get_apps_menu               (void);

Retrieves FmPath for menu:// virtual directory. Returned data are owned by `path` and should be not freed by caller.

Returns : | a path.

Since 0.1.0

### fm_path_get_basename ()

    const char *        fm_path_get_basename                (FmPath *path);

Retrieves basename of `path`. Returned data are owned by `path` and should be not freed by caller.

`path` : | a path
Returns : | basename of path.

Since 0.1.0

### fm_path_get_desktop ()

    FmPath *            fm_path_get_desktop                 (void);

Retrieves FmPath for desktop directory. Returned data are owned by `path` and should be not freed by caller.

Returns : | a path.

Since 0.1.0

### fm_path_get_flags ()

    FmPathFlags         fm_path_get_flags                   (FmPath *path);

Retrieves attributes of `path`.

`path` : | a path
Returns : | attributes of path.

Since 0.1.0

### fm_path_get_home ()

    FmPath *            fm_path_get_home                    (void);

Retrieves FmPath for home directory. Returned data are owned by `path` and should be not freed by caller.

Returns : | a path.

Since 0.1.0

### fm_path_get_parent ()

    FmPath *            fm_path_get_parent                  (FmPath *path);

Retrieves path of directory containing `path`. Returned data are owned by `path` and should be not freed by caller.

`path` : | a path
Returns : | path of parent directory or `NULL` if `path` is root path. [transfer none]

Since 0.1.0

### fm_path_get_root ()

    FmPath *            fm_path_get_root                    (void);

Retrieves FmPath for root directory. Returned data are owned by `path` and should be not freed by caller.

Returns : | a path.

Since 0.1.0

### fm_path_get_scheme_path ()

    FmPath *            fm_path_get_scheme_path             (FmPath *path);

Retrieves a root path for scheme used by `path`. If `path` is a local path then returned data are the same as returned with `fm_path_get_root()`. Returned data are owned by `path` and should be not freed by caller.

`path` : | a path
Returns : | path of root of `path` scheme. [transfer none]

Since 1.2.0

### fm_path_get_trash ()

    FmPath *            fm_path_get_trash                   (void);

Retrieves FmPath for Trash can. Returned data are owned by `path` and should be not freed by caller.

Returns : | a path.

Since 0.1.0

### 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);

Converts a path to a hash value.

`path` : | a path key
Returns : | a hash value corresponding to the key.

Since 0.1.0

### fm_path_is_local()

    #define fm_path_is_local(path) ((fm_path_get_flags(path)&FM_PATH_IS_LOCAL)!=0)

### Warning

`fm_path_is_local` is deprecated and should not be used in newly-written code.

### fm_path_is_native()

    #define fm_path_is_native(path) ((fm_path_get_flags(path)&FM_PATH_IS_NATIVE)!=0)

### fm_path_is_native_or_trash()

    #define fm_path_is_native_or_trash(path) ((fm_path_get_flags(path)&(FM_PATH_IS_NATIVE|FM_PATH_IS_TRASH))!=0)

### fm_path_is_trash()

    #define fm_path_is_trash(path) ((fm_path_get_flags(path)&FM_PATH_IS_TRASH)!=0)

### 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)!=0)

### Warning

`fm_path_is_virtual` is deprecated and should not be used in newly-written code.

### fm_path_is_xdg_menu()

    #define fm_path_is_xdg_menu(path) ((fm_path_get_flags(path)&FM_PATH_IS_XDG_MENU)!=0)

### Warning

`fm_path_is_xdg_menu` is deprecated and should not be used in newly-written code.

### fm_path_list_new ()

    FmPathList *        fm_path_list_new                    (void);

### fm_path_list_new_from_file_info_glist ()

    FmPathList *        fm_path_list_new_from_file_info_glist
                                                            (GList *fis);

Creates a FmPathList from `fis`.

`fis` : | list of file infos. [element-type FmFileInfo]
Returns : | new FmPathList. [transfer full]

Since 0.1.0

### fm_path_list_new_from_file_info_gslist ()

    FmPathList *        fm_path_list_new_from_file_info_gslist
                                                            (GSList *fis);

Creates a FmPathList from `fis`.

`fis` : | list of file infos. [element-type FmFileInfo]
Returns : | new FmPathList. [transfer full]

Since 0.1.0

### fm_path_list_new_from_file_info_list ()

    FmPathList *        fm_path_list_new_from_file_info_list
                                                            (FmFileInfoList *fis);

Creates a FmPathList from `fis`.

`fis` : | a file info list
Returns : | new FmPathList. [transfer full]

Since 0.1.0

### fm_path_list_new_from_uri_list ()

    FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);

Creates a FmPathList from `uri_list`.

`uri_list` : | list of URIs separated by newline characters
Returns : | new FmPathList. [transfer full]

Since 0.1.0

### fm_path_list_new_from_uris ()

    FmPathList *        fm_path_list_new_from_uris          (char * const*uris);

Creates a FmPathList from `uris`.

`uris` : | NULL-terminated list of URIs
Returns : | new FmPathList. [transfer full]

Since 0.1.0

### fm_path_list_to_uri_list ()

    char *              fm_path_list_to_uri_list            (FmPathList *pl);

Creates newline-separated list from `pl`. Returned data should be freed with `g_free()` after usage.

`pl` : | a path list
Returns : | string representation of `pl`. [transfer full]

Since 0.1.0

### fm_path_list_write_uri_list ()

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

Creates newline-separated list of URIs from `pl`.

`pl` : | a path list
`buf` : | a storage for resulting list. [out]

Since 0.1.0

### fm_path_new_child ()

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

Creates new FmPath for child of `parent` directory which have name `basename`. `basename` is in glib filename encoding (can be non-UTF-8) of target filesystem.

`parent` : | a parent path. [allow-none]
`basename` : | basename of a direct child of `parent` directory. [allow-none]
Returns : | a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed. [transfer full]

### fm_path_new_child_len ()

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

Creates new FmPath for child of `parent` directory which have name `basename`. The string length of `basename` is `name_len`. `basename` is in glib filename encoding (can be non-UTF-8) of target filesystem. If `parent` is `NULL` then `basename` assumed to be root of some file system.

`parent` : | a parent path. [allow-none]
`basename` : | basename of a direct child of `parent` directory. [allow-none]
`name_len` : | length of `basename`
Returns : | a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed. [transfer full]

### 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);

The `path_name` can either be a POSIX path in UTF-8 encoding, or an unescaped URI (can contain non-ASCII characters and spaces). Returned data should be freed with `fm_path_unref()` when it's no longer needed. Display name may be fully unrelated to it's path name and built path may be inexistant. Use FmJob to check and validate its existance.

`path_name` : | an UTF-8 encoded display path name
Returns : | a newly created FmPath.

Since 0.1.14

### 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. [allow-none]
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. [allow-none]
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);

Creates new FmPath by given `uri`. You have to call `fm_path_unref()` when it's no longer needed.

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

This function never fail but it may return root path if URI is local and contains illegal characters in path elements such as '/'.

`uri` : | a URI with special characters escaped. [allow-none]
Returns : | a new FmPath for the `uri`. [transfer full]

### fm_path_new_relative ()

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

Creates new FmPath which is relative to `parent` directory by the relative path string `rel`. `rel` is in glib filename encoding (can be non-UTF-8) if `parent` is native and should be escaped URI subpath otherwise. For example, if `parent` is "http://wiki.lxde.org/" and `rel` is "zh/%E9%A6%96%E9%A0%81", the resulting path will be "http://wiki.lxde.org/zh/%E9%A6%96%E9%A0%81".

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

`parent` : | a parent path. [allow-none]
`rel` : | a path relative to `parent`. [allow-none]
Returns : | a new FmPath for the path. You have to call `fm_path_unref()` when it's no longer needed. [transfer full]

### fm_path_ref ()

    FmPath *            fm_path_ref                         (FmPath *path);

Increases reference count on `path`.

`path` : | an existing FmPath
Returns : | `path`.

### fm_path_to_gfile ()

    GFile *             fm_path_to_gfile                    (FmPath *path);

Creates GFile representation of `path`. Returned data should be freed with `g_object_unref()` after usage.

`path` : | a path
Returns : | a GFile object. [transfer full]

Since 0.1.0

### fm_path_to_str ()

    char *              fm_path_to_str                      (FmPath *path);

Creates string representation of `path`. It can be either file path in local encoding or URI with non-ASCII characters escaped (RFC 3986). Returned data should be freed with `g_free()` after usage.

`path` : | a path
Returns : | path string. [transfer full]

Since 0.1.0

### fm_path_to_uri ()

    char *              fm_path_to_uri                      (FmPath *path);

Creates URI representation of `path`. Returned data should be freed with `g_free()` after usage.

`path` : | a path
Returns : | path URI.

Since 0.1.0

### fm_path_unref ()

    void                fm_path_unref                       (FmPath *path);

Decreases reference count on `path`. When reference count becomes 0 the `path` will be destroyed.

`path` : | an existing FmPath