Core Misc

## Core Misc Core Misc — The Core Library Utilities |

## Synopsis

    #include <caja-action/na-core-utils.h>

    gboolean            na_core_utils_boolean_from_string   (const gchar *string);
    gchar *             na_core_utils_str_add_prefix        (const gchar *prefix,
                                                             const gchar *str);
    int                 na_core_utils_str_collate           (const gchar *str1,
                                                             const gchar *str2);
    gchar *             na_core_utils_str_remove_char       (const gchar *string,
                                                             const gchar *to_remove);
    gchar *             na_core_utils_str_remove_suffix     (const gchar *string,
                                                             const gchar *suffix);
    void                na_core_utils_str_split_first_word  (const gchar *string,
                                                             gchar **first,
                                                             gchar **other);
    gchar *             na_core_utils_str_subst             (const gchar *pattern,
                                                             const gchar *key,
                                                             const gchar *subst);
    void                na_core_utils_slist_add_message     (GSList **list,
                                                             const gchar *format,
                                                             ...);
    GSList *            na_core_utils_slist_duplicate       (GSList *slist);
    void                na_core_utils_slist_dump            (const gchar *prefix,
                                                             GSList *list);
    GSList *            na_core_utils_slist_from_array      (const gchar **str_array);
    GSList *            na_core_utils_slist_from_split      (const gchar *text,
                                                             const gchar *separator);
    gchar *             na_core_utils_slist_join_at_end     (GSList *slist,
                                                             const gchar *link);
    GSList *            na_core_utils_slist_remove_ascii    (GSList *slist,
                                                             const gchar *text);
    GSList *            na_core_utils_slist_remove_utf8     (GSList *slist,
                                                             const gchar *text);
    gchar **            na_core_utils_slist_to_array        (GSList *slist);
    gchar *             na_core_utils_slist_to_text         (GSList *slist);
    GSList *            na_core_utils_slist_setup_element   (GSList *list,
                                                             const gchar *element,
                                                             gboolean set);
    guint               na_core_utils_slist_count           (GSList *list,
                                                             const gchar *str);
    gboolean            na_core_utils_slist_find_negated    (GSList *list,
                                                             const gchar *str);
    gboolean            na_core_utils_slist_are_equal       (GSList *a,
                                                             GSList *b);
    void                na_core_utils_slist_free            (GSList *slist);
    gchar *             na_core_utils_gstring_joinv         (const gchar *start,
                                                             const gchar *separator,
                                                             gchar **list);
    void                na_core_utils_selcount_get_ope_int  (const gchar *selection_count,
                                                             gchar **ope,
                                                             gchar **uint);
    gboolean            na_core_utils_dir_is_writable_path  (const gchar *path);
    gboolean            na_core_utils_dir_is_writable_uri   (const gchar *uri);
    void                na_core_utils_dir_list_perms        (const gchar *path,
                                                             const gchar *message);
    void                na_core_utils_dir_split_ext         (const gchar *string,
                                                             gchar **first,
                                                             gchar **ext);
    gboolean            na_core_utils_file_delete           (const gchar *path);
    gboolean            na_core_utils_file_exists           (const gchar *uri);
    gboolean            na_core_utils_file_is_loadable      (const gchar *uri);
    gchar *             na_core_utils_file_load_from_uri    (const gchar *uri,
                                                             gsize *length);
    void                na_core_utils_print_version         (void);

## Description

## Details

### na_core_utils_boolean_from_string ()

    gboolean            na_core_utils_boolean_from_string   (const gchar *string);

`string` : | a string to be converted.
Returns : | `TRUE` if the string evaluates to "true" (case insensitive), `FALSE` else.

Since 2.30

### na_core_utils_str_add_prefix ()

    gchar *             na_core_utils_str_add_prefix        (const gchar *prefix,
                                                             const gchar *str);

### Warning

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

Appends a prefix to each line of the string.

`prefix` : | the prefix to be prepended.
`str` : | a multiline string.
Returns : | a new string which should be `g_free()` by the caller.

Since 2.30

### na_core_utils_str_collate ()

    int                 na_core_utils_str_collate           (const gchar *str1,
                                                             const gchar *str2);

`str1` : | an UTF-8 encoded string.
`str2` : | an UTF-8 encoded string.
Returns : | -1 if str1 < str2, 0 if str1 = str2, +1 if str1 > str2.

Since 2.30

### na_core_utils_str_remove_char ()

    gchar *             na_core_utils_str_remove_char       (const gchar *string,
                                                             const gchar *to_remove);

`string` : | source string.
`to_remove` : | the character to remove.
Returns : | a newly allocated string, which is a copy of the source `string`, minus all the found occurrences of the given `to_remove` char. The returned string should be `g_free()` by the caller.

Since 2.30

### na_core_utils_str_remove_suffix ()

    gchar *             na_core_utils_str_remove_suffix     (const gchar *string,
                                                             const gchar *suffix);

`string` : | source string.
`suffix` : | suffix to be removed from `string`.
Returns : | a newly allocated string, which is a copy of the source `string`, minus the removed `suffix` if present. If `strings` doesn't terminate with `suffix`, then the returned string is equal to source `string`. The returned string should be `g_free()` by the caller.

Since 2.30

### na_core_utils_str_split_first_word ()

    void                na_core_utils_str_split_first_word  (const gchar *string,
                                                             gchar **first,
                                                             gchar **other);

Split the `string` string into two components:

- the first word which is allocated in `first`,

- the rest of the string which is allocated in `other`.

The two allocated strings should be `g_free()` by the caller.

`string` : | a space-separated string.
`first` : | a pointer to a gchar *.
`other` : | a pointer to a gchar *.

Since 2.30

### na_core_utils_str_subst ()

    gchar *             na_core_utils_str_subst             (const gchar *pattern,
                                                             const gchar *key,
                                                             const gchar *subst);

`pattern` : | the pattern.
`key` : | the key string to be substituted.
`subst` : | the string which will replace `key`.
Returns : | a copy of `pattern` where the first occurrence of `key` has been substituted with `subst`, as a newly allocated string which should be `g_free()` by the caller, or a copy of `pattern` if `key` is not found in `pattern`.

### na_core_utils_slist_add_message ()

    void                na_core_utils_slist_add_message     (GSList **list,
                                                             const gchar *format,
                                                             ...);

### na_core_utils_slist_duplicate ()

    GSList *            na_core_utils_slist_duplicate       (GSList *slist);

`slist` : | the GSList to be duplicated.
Returns : | a GSList of strings. The returned list should be `na_core_utils_slist_free()` by the caller.

Since 2.30

### na_core_utils_slist_dump ()

    void                na_core_utils_slist_dump            (const gchar *prefix,
                                                             GSList *list);

Dumps the content of a list of strings.

`prefix` : | a string to be used as a prefix for each outputed line.
`list` : | a list of strings.

Since 2.30

### na_core_utils_slist_from_array ()

    GSList *            na_core_utils_slist_from_array      (const gchar **str_array);

`str_array` : | an NULL-terminated array of strings.
Returns : | a GSList list of strings, which should be #`na_core_utils_slist_free()` by the caller.

Since 2.30

### na_core_utils_slist_from_split ()

    GSList *            na_core_utils_slist_from_split      (const gchar *text,
                                                             const gchar *separator);

`text` : | a string to be splitted.
`separator` : | the string to be used as the separator.
Returns : | a GSList with the list of strings after having been splitted. The returned GSList should be `na_core_utils_slist_free()` by the caller.

Since 2.30

### na_core_utils_slist_join_at_end ()

    gchar *             na_core_utils_slist_join_at_end     (GSList *slist,
                                                             const gchar *link);

`slist` : | the string list to join.
`link` : | the string used to join each element.
Returns : | a newly allocated string which should be `g_free()` by the caller.

Since 2.30

### na_core_utils_slist_remove_ascii ()

    GSList *            na_core_utils_slist_remove_ascii    (GSList *slist,
                                                             const gchar *text);

Removes a string from a GSList of strings.

`slist` : | the GSList to be updated.
`text` : | string to remove.
Returns : | the same, updated, `slist`.

Since 2.30

### na_core_utils_slist_remove_utf8 ()

    GSList *            na_core_utils_slist_remove_utf8     (GSList *slist,
                                                             const gchar *text);

Removes from the `slist` the item which has a string which is equal to `text`.

`slist` : | the GSList to be updated.
`text` : | the string to be removed.
Returns : | the new `slist` start position.

Since 2.30

### na_core_utils_slist_to_array ()

    gchar **            na_core_utils_slist_to_array        (GSList *slist);

`slist` : | a list of strings.
Returns : | a newly allocated array of strings, which should be `g_strfreev()` by the caller.

Since 2.30

### na_core_utils_slist_to_text ()

    gchar *             na_core_utils_slist_to_text         (GSList *slist);

Concatenates a string list to a semi-colon-separated text suitable for an entry in the user interface

`slist` : | a list of strings.
Returns : | a newly allocated string, which should be `g_free()` by the caller.

Since 2.30

### na_core_utils_slist_setup_element ()

    GSList *            na_core_utils_slist_setup_element   (GSList *list,
                                                             const gchar *element,
                                                             gboolean set);

Setup the `list` so that the `element` is once in the `list` if `set` is `TRUE`, or not if `set` is `FALSE`.

`list` : | the GSList of strings to be setup.
`element` : | the string to add to or remove of the list.
`set` : | whether the `element` should be set or removed.
Returns : | the updated `list`.

Since 2.30

### na_core_utils_slist_count ()

    guint               na_core_utils_slist_count           (GSList *list,
                                                             const gchar *str);

Search for a string in a string list.

`list` : | the GSList of strings to be searched.
`str` : | the searched string.
Returns : | the count of @ßtr in `list` list.

Since 2.30

### na_core_utils_slist_find_negated ()

    gboolean            na_core_utils_slist_find_negated    (GSList *list,
                                                             const gchar *str);

Search for a string in a string list which may contain nagated items.

`list` : | the GSList of strings to be searched.
`str` : | the searched string.
Returns : | `TRUE` if the string has been found in list.

Since 2.30

### na_core_utils_slist_are_equal ()

    gboolean            na_core_utils_slist_are_equal       (GSList *a,
                                                             GSList *b);

Compare two string lists, without regards to the order.

`a` : | a GSList of strings.
`b` : | another GSList of strings to be compared with `first`.
Returns : | `TRUE` if the two lists have same content.

Since 2.30

### na_core_utils_slist_free ()

    void                na_core_utils_slist_free            (GSList *slist);

Releases the strings and the list itself.

`slist` : | a GSList list of strings.

Since 2.30

### na_core_utils_gstring_joinv ()

    gchar *             na_core_utils_gstring_joinv         (const gchar *start,
                                                             const gchar *separator,
                                                             gchar **list);

Concatenates a gchar **list of strings to a new string.

`start` : | a prefix to be written at the beginning of the output string.
`separator` : | a string to be used as separator.
`list` : | the list of strings to be concatenated.
Returns : | a newly allocated string which should be `g_free()` by the caller.

Since 2.30

### na_core_utils_selcount_get_ope_int ()

    void                na_core_utils_selcount_get_ope_int  (const gchar *selection_count,
                                                             gchar **ope,
                                                             gchar **uint);

### na_core_utils_dir_is_writable_path ()

    gboolean            na_core_utils_dir_is_writable_path  (const gchar *path);

`path` : | the path of the directory to be tested.
Returns : | `TRUE` if the directory is writable, `FALSE` else. Please note that this type of test is subject to race conditions, as the directory may become unwritable after a successful test, but before the caller has been able to actually write into it. There is no "super-test". Just try...

Since 2.30

### na_core_utils_dir_is_writable_uri ()

    gboolean            na_core_utils_dir_is_writable_uri   (const gchar *uri);

`uri` : | the URI of the directory to be tested.
Returns : | `TRUE` if the directory is writable, `FALSE` else. Please note that this type of test is subject to race conditions, as the directory may become unwritable after a successful test, but before the caller has been able to actually write into it. There is no "super-test". Just try...

Since 2.30

### na_core_utils_dir_list_perms ()

    void                na_core_utils_dir_list_perms        (const gchar *path,
                                                             const gchar *message);

Displays the permissions of the directory on debug output.

`path` : | the path of the directory to be tested.
`message` : | a message to be printed if not `NULL`.

Since 3.1

### na_core_utils_dir_split_ext ()

    void                na_core_utils_dir_split_ext         (const gchar *string,
                                                             gchar **first,
                                                             gchar **ext);

Split the given `string`, returning the first part and the extension in newly allocated buffers which should be `g_free()` by the caller.

The extension is set to an empty string if no extension is detected.

`string` : | the input path or URI to be splitted.
`first` : | a pointer to a buffer which will contain the first part of the split.
`ext` : | a pointer to a buffer which will contain the extension part of the path.

Since 2.30

### na_core_utils_file_delete ()

    gboolean            na_core_utils_file_delete           (const gchar *path);

`path` : | the path of the file to be deleted.
Returns : | `TRUE` if the file is successfully deleted, `FALSE` else.

Since 2.30

### na_core_utils_file_exists ()

    gboolean            na_core_utils_file_exists           (const gchar *uri);

`uri` : | a file URI.
Returns : | `TRUE` if the specified file exists, `FALSE` else. Race condition: cf. `na_core_utils_dir_is_writable_path()` and `na_core_utils_dir_is_writable_uri()` comments.

Since 2.30

### na_core_utils_file_is_loadable ()

    gboolean            na_core_utils_file_is_loadable      (const gchar *uri);

Checks that the file is suitable to be loaded in memory, because it is not empty, and its size is reasonable (less than 1MB). Also checks that a file is a regular file (or a symlink to a regular file).

`uri` : | the URI to be checked.
Returns : | whether the file is suitable to be loaded in memory.

Since 3.1

### na_core_utils_file_load_from_uri ()

    gchar *             na_core_utils_file_load_from_uri    (const gchar *uri,
                                                             gsize *length);

Loads the file into a newly allocated buffer, and set up the length of the read content if not `NULL`.

`uri` : | the URI the file must be loaded from.
`length` : | a pointer to the length of the read content.
Returns : | the newly allocated buffer which contains the file content, or `NULL`. This buffer should be `g_free()` by the caller.

Since 2.30

### na_core_utils_print_version ()

    void                na_core_utils_print_version         (void);

Print a version message on the console

      caja-actions-new (Caja-Actions) v 2.29.1
      Copyright (C) 2005-2007 Frederic Ruaudel
      Copyright (C) 2009, 2010, 2011, 2012 Pierre Wieser
      Caja-Actions is free software, licensed under GPLv2 or later.

Since 2.30