utils.h File Reference

General utility functions, non-GTK related. More...

Macros
#define	EMPTY(ptr)    (!(ptr) || !*(ptr))
	Returns TRUE if ptr is NULL or *ptr is FALSE.
#define	foreach_array(type, item, array)    foreach_c_array(item, ((type*)(gpointer)array->data), array->len)
	Iterates all items in array. More...
#define	foreach_c_array(item, array, len)    for (item = array; item < &array[len]; item++)
	Iterates all the items in array using pointers. More...
#define	foreach_dir(filename, dir)    for ((filename) = g_dir_read_name(dir); (filename) != NULL; (filename) = g_dir_read_name(dir))
	Iterates through each unsorted filename in a GDir. More...
#define	foreach_list(node, list)    for (node = list; node != NULL; node = node->next)
	Iterates all the nodes in list. More...
#define	foreach_ptr_array(item, idx, ptr_array)    for (idx = 0; idx < (ptr_array)->len && (item = g_ptr_array_index((ptr_array), idx), TRUE); ++idx)
	Iterates all the pointers in ptr_array. More...
#define	foreach_range(i, size)    for (i = 0; i < size; i++)
	Iterates from 0 to size. More...
#define	foreach_slist(node, list)    foreach_list(node, list)
	Iterates all the nodes in list. More...
#define	foreach_str(char_ptr, string)    for (char_ptr = string; *char_ptr; char_ptr++)
	Iterates through each character in string. More...
#define	foreach_strv(str_ptr, strv)    if (!(strv)) {} else foreach_str(str_ptr, strv)
	Iterates a null-terminated string vector. More...
#define	NZV(ptr)   (!EMPTY(ptr))
#define	SETPTR(ptr, result)
	Assigns result to ptr, then frees the old value. More...
#define	setptr(ptr, result)
#define	utils_strdupa(str)    strcpy(g_alloca(strlen(str) + 1), str)
	Duplicates a string on the stack using g_alloca(). More...

Functions
gchar **	utils_copy_environment (const gchar **exclude_vars, const gchar *first_varname,...) G_GNUC_NULL_TERMINATED
	Copies the current environment into a new array. More...
gchar *	utils_find_open_xml_tag (const gchar sel[], gint size)
	Searches backward through size bytes looking for a '<'. More...
const gchar *	utils_find_open_xml_tag_pos (const gchar sel[], gint size)
	Searches backward through size bytes looking for a '<'. More...
gchar *	utils_get_date_time (const gchar *format, time_t *time_to_use)
	Retrieves a formatted date/time string from GDateTime. More...
GSList *	utils_get_file_list (const gchar *path, guint *length, GError **error)
	Gets a sorted list of files from the specified directory. More...
GSList *	utils_get_file_list_full (const gchar *path, gboolean full_path, gboolean sort, GError **error)
	Gets a list of files from the specified directory. More...
gchar *	utils_get_locale_from_utf8 (const gchar *utf8_text)
	Converts the given UTF-8 encoded string into locale encoding. More...
gchar *	utils_get_real_path (const gchar *file_name)
	Get a link-dereferenced, absolute version of a file name. More...
gboolean	utils_get_setting_boolean (GKeyFile *config, const gchar *section, const gchar *key, const gboolean default_value)
	Wraps g_key_file_get_boolean() to add a default value argument. More...
gdouble	utils_get_setting_double (GKeyFile *config, const gchar *section, const gchar *key, const gdouble default_value)
	Wraps g_key_file_get_double() to add a default value argument. More...
gint	utils_get_setting_integer (GKeyFile *config, const gchar *section, const gchar *key, const gint default_value)
	Wraps g_key_file_get_integer() to add a default value argument. More...
gchar *	utils_get_setting_string (GKeyFile *config, const gchar *section, const gchar *key, const gchar *default_value)
	Wraps g_key_file_get_string() to add a default value argument. More...
gchar *	utils_get_utf8_from_locale (const gchar *locale_text)
	Converts the given string (in locale encoding) into UTF-8 encoding. More...
gint	utils_mkdir (const gchar *path, gboolean create_parent_dirs)
	Creates a directory if it doesn't already exist. More...
void	utils_open_browser (const gchar *uri)
	Tries to open the given URI in a browser. More...
gchar *	utils_remove_ext_from_filename (const gchar *filename)
	Removes the extension from filename and return the result in a newly allocated string. More...
gboolean	utils_spawn_async (const gchar *dir, gchar **argv, gchar **env, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, GError **error)
	Wraps spawn_async(), which see. More...
gboolean	utils_spawn_sync (const gchar *dir, gchar **argv, gchar **env, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gchar **std_out, gchar **std_err, gint *exit_status, GError **error)
	Wraps spawn_sync(), which see. More...
gint	utils_str_casecmp (const gchar *s1, const gchar *s2)
	A replacement function for g_strncasecmp() to compare strings case-insensitive. More...
gboolean	utils_str_equal (const gchar *a, const gchar *b)
	NULL-safe string comparison. More...
gchar *	utils_str_middle_truncate (const gchar *string, guint truncate_length)
	Truncates the input string to a given length. More...
gchar *	utils_str_remove_chars (gchar *string, const gchar *chars)
	Removes characters from a string, in place. More...
guint	utils_string_replace_all (GString *haystack, const gchar *needle, const gchar *replace)
	Replaces all occurrences of needle in haystack with replace. More...
guint	utils_string_replace_first (GString *haystack, const gchar *needle, const gchar *replace)
	Replaces only the first occurrence of needle in haystack with replace. More...
gchar **	utils_strv_shorten_file_list (gchar **file_names, gssize file_names_len)
	Transform file names in a list to be shorter. More...
gint	utils_write_file (const gchar *filename, const gchar *text)
	Writes text into a file named filename. More...

Detailed Description

General utility functions, non-GTK related.

Macro Definition Documentation

foreach_array

#define foreach_array	(		type,
			item,
			array
	)		foreach_c_array(item, ((type*)(gpointer)array->data), array->len)

Iterates all items in array.

Parameters

type	Type of item.
item	pointer to item in array.
array	GArray to traverse.

foreach_c_array

#define foreach_c_array	(		item,
			array,
			len
	)		for (item = array; item < &array[len]; item++)

Iterates all the items in array using pointers.

Parameters

item	pointer to an item in array.
array	C array to traverse.
len	Length of the array.

foreach_dir

#define foreach_dir	(		filename,
			dir
	)		for ((filename) = g_dir_read_name(dir); (filename) != NULL; (filename) = g_dir_read_name(dir))

Iterates through each unsorted filename in a GDir.

Parameters

filename	(const gchar*) locale-encoded filename, without path. Do not modify or free.
dir	GDir created with g_dir_open(). Call g_dir_close() afterwards.

See also

utils_get_file_list() if you want a sorted list.

Since

Geany 0.19.

foreach_list

#define foreach_list	(		node,
			list
	)		for (node = list; node != NULL; node = node->next)

Iterates all the nodes in list.

Parameters

node	should be a (GList*).
list	GList to traverse.

foreach_ptr_array

#define foreach_ptr_array	(		item,
			idx,
			ptr_array
	)		for (idx = 0; idx < (ptr_array)->len && (item = g_ptr_array_index((ptr_array), idx), TRUE); ++idx)

Iterates all the pointers in ptr_array.

Parameters

item	pointer in ptr_array.
idx	guint index into ptr_array.
ptr_array	GPtrArray to traverse.

foreach_range

#define foreach_range	(		i,
			size
	)		for (i = 0; i < size; i++)

Iterates from 0 to size.

Parameters

i	Integer.
size	Number of iterations.

Since

Geany 0.20.

foreach_slist

#define foreach_slist	(		node,
			list
	)		foreach_list(node, list)

Iterates all the nodes in list.

Parameters

node	should be a (GSList*).
list	GSList to traverse.

foreach_str

#define foreach_str	(		char_ptr,
			string
	)		for (char_ptr = string; *char_ptr; char_ptr++)

Iterates through each character in string.

Parameters

char_ptr	Pointer to character.
string	String to traverse.

Warning

Doesn't include null terminating character.

Since

Geany 0.19.

foreach_strv

#define foreach_strv	(		str_ptr,
			strv
	)		if (!(strv)) {} else foreach_str(str_ptr, strv)

Iterates a null-terminated string vector.

Parameters

str_ptr	gchar** pointer to string element.
strv	Can be NULL.

Since

Geany 0.20

NZV

#define NZV

(

ptr

)

(!EMPTY(ptr))

Deprecated:

2013/08 - use !EMPTY() instead.

SETPTR

#define SETPTR	(		ptr,
			result
	)

Value:

    do {\
        gpointer setptr_tmp = ptr;\
        ptr = result;\
        g_free(setptr_tmp);\
    } while (0)

Assigns result to ptr, then frees the old value.

result can be an expression using the 'old' value of ptr. E.g.

SETPTR(str, g_strndup(str, 5)); 

setptr

#define setptr	(		ptr,
			result
	)

Value:

    {\
        gpointer setptr_tmp = ptr;\
        ptr = result;\
        g_free(setptr_tmp);\
    }

Deprecated:

2011/11/15 - use SETPTR() instead.

utils_strdupa

#define utils_strdupa

(

str

)

strcpy(g_alloca(strlen(str) + 1), str)

Duplicates a string on the stack using g_alloca().

Like glibc's strdupa(), but portable.

Note

You must include string.h yourself.

Warning

Don't use excessively or for long strings otherwise there may be stack exhaustion - see the GLib docs for g_alloca().

Function Documentation

utils_copy_environment()

gchar ** utils_copy_environment	(	const gchar **	exclude_vars,
		const gchar *	first_varname,
			...
	)

Copies the current environment into a new array.

exclude_vars is a NULL-terminated array of variable names which should be not copied. All further arguments are key, value pairs of variables which should be added to the environment.

The argument list must be NULL-terminated.

Parameters

exclude_vars	NULL-terminated array of variable names to exclude.
first_varname	Name of the first variable to copy into the new array.
...	Key-value pairs of variable names and values, NULL-terminated.

Returns

(transfer: full) The new environment array. Use g_strfreev() to free it.

utils_find_open_xml_tag()

gchar * utils_find_open_xml_tag	(	const gchar	sel[],
		gint	size
	)

Searches backward through size bytes looking for a '<'.

Parameters

sel	.
size	.

Returns

The tag name (newly allocated) or NULL if no opening tag was found.

utils_find_open_xml_tag_pos()

const gchar * utils_find_open_xml_tag_pos	(	const gchar	sel[],
		gint	size
	)

Searches backward through size bytes looking for a '<'.

Parameters

sel	.
size	.

Returns

pointer to '<' of the found opening tag within sel, or NULL if no opening tag was found.

utils_get_date_time()

gchar * utils_get_date_time	(	const gchar *	format,
		time_t *	time_to_use
	)

Retrieves a formatted date/time string from GDateTime.

This function works on UTF-8 encoded strings.

Parameters

format	The format string to pass to g_date_time_format, in UTF-8 encoding. See https://docs.gtk.org/glib/method.DateTime.format.html for details.
time_to_use	The date/time to use, in time_t format or NULL to use the current time.

Returns

A newly-allocated string, should be freed when no longer needed.

Since

0.16

utils_get_file_list()

GSList * utils_get_file_list	(	const gchar *	path,
		guint *	length,
		GError **	error
	)

Gets a sorted list of files from the specified directory.

Locale encoding is expected for path and used for the file list. The list and the data in the list should be freed after use, e.g.:

g_slist_foreach(list, (GFunc) g_free, NULL);
g_slist_free(list); 

Parameters

path	The path of the directory to scan, in locale encoding.
length	The location to store the number of non-NULL data items in the list, unless NULL.
error	The location for storing a possible error, or NULL.

Returns

(element-type: filename) (transfer: full) A newly allocated list or NULL if no files were found. The list and its data should be freed when no longer needed.

See also

utils_get_file_list_full().

utils_get_file_list_full()

GSList * utils_get_file_list_full	(	const gchar *	path,
		gboolean	full_path,
		gboolean	sort,
		GError **	error
	)

Gets a list of files from the specified directory.

Locale encoding is expected for path and used for the file list. The list and the data in the list should be freed after use, e.g.:

g_slist_foreach(list, (GFunc) g_free, NULL);
g_slist_free(list); 

Note

If you don't need a list you should use the foreach_dir() macro instead - it's more efficient.

Parameters

path	The path of the directory to scan, in locale encoding.
full_path	Whether to include the full path for each filename in the list. Obviously this will use more memory.
sort	Whether to sort alphabetically (UTF-8 safe).
error	The location for storing a possible error, or NULL.

Returns

(element-type: filename) (transfer: full) A newly allocated list or NULL if no files were found. The list and its data should be freed when no longer needed.

See also

utils_get_file_list().

utils_get_locale_from_utf8()

gchar * utils_get_locale_from_utf8

(

const gchar *

utf8_text

)

Converts the given UTF-8 encoded string into locale encoding.

On Windows platforms, it does nothing and instead it just returns a copy of the input string.

Parameters

utf8_text

UTF-8 encoded text.

Returns

The converted string in locale encoding, or a copy of the input string if conversion failed. Should be freed with g_free(). If utf8_text is NULL, NULL is returned.

utils_get_real_path()

gchar * utils_get_real_path

(

const gchar *

file_name

)

Get a link-dereferenced, absolute version of a file name.

This is similar to the POSIX realpath function when passed a NULL argument.

Warning

This function suffers the same problems as the POSIX function realpath(), namely that it's impossible to determine a suitable size for the returned buffer, and so it's limited to a maximum of PATH_MAX.

Parameters

file_name

The file name to get the real path of.

Returns

A newly-allocated string containing the real path which should be freed with g_free() when no longer needed, or NULL if the real path cannot be obtained.

Since

1.32 (API 235)

utils_get_setting_boolean()

gboolean utils_get_setting_boolean	(	GKeyFile *	config,
		const gchar *	section,
		const gchar *	key,
		const gboolean	default_value
	)

Wraps g_key_file_get_boolean() to add a default value argument.

Parameters

config	A GKeyFile object.
section	The group name to look in for the key.
key	The key to find.
default_value	The default value which will be returned when section or key don't exist.

Returns

The value associated with key as a boolean, or the given default value if the value could not be retrieved.

utils_get_setting_double()

gdouble utils_get_setting_double	(	GKeyFile *	config,
		const gchar *	section,
		const gchar *	key,
		const gdouble	default_value
	)

Wraps g_key_file_get_double() to add a default value argument.

Parameters

config	A GKeyFile object.
section	The group name to look in for the key.
key	The key to find.
default_value	The default value which will be returned when section or key don't exist.

Returns

The value associated with key as an integer, or the given default value if the value could not be retrieved.

utils_get_setting_integer()

gint utils_get_setting_integer	(	GKeyFile *	config,
		const gchar *	section,
		const gchar *	key,
		const gint	default_value
	)

Wraps g_key_file_get_integer() to add a default value argument.

Parameters

config	A GKeyFile object.
section	The group name to look in for the key.
key	The key to find.
default_value	The default value which will be returned when section or key don't exist.

Returns

The value associated with key as an integer, or the given default value if the value could not be retrieved.

utils_get_setting_string()

gchar * utils_get_setting_string	(	GKeyFile *	config,
		const gchar *	section,
		const gchar *	key,
		const gchar *	default_value
	)

Wraps g_key_file_get_string() to add a default value argument.

Parameters

config	A GKeyFile object.
section	The group name to look in for the key.
key	The key to find.
default_value	The default value which will be returned when section or key don't exist.

Returns

A newly allocated string, either the value for key or a copy of the given default value if it could not be retrieved.

utils_get_utf8_from_locale()

gchar * utils_get_utf8_from_locale

(

const gchar *

locale_text

)

Converts the given string (in locale encoding) into UTF-8 encoding.

On Windows platforms, it does nothing and instead it just returns a copy of the input string.

Parameters

locale_text

Text in locale encoding.

Returns

The converted string in UTF-8 encoding, or a copy of the input string if conversion failed. Should be freed with g_free(). If locale_text is NULL, NULL is returned.

utils_mkdir()

gint utils_mkdir	(	const gchar *	path,
		gboolean	create_parent_dirs
	)

Creates a directory if it doesn't already exist.

Creates intermediate parent directories as needed, too. The permissions of the created directory are set 0700.

Parameters

path	The path of the directory to create, in locale encoding.
create_parent_dirs	Whether to create intermediate parent directories if necessary.

Returns

0 if the directory was successfully created, otherwise the errno of the failed operation is returned.

utils_open_browser()

void utils_open_browser

(

const gchar *

uri

)

Tries to open the given URI in a browser.

On Windows, the system's default browser is opened. On non-Windows systems, the browser command can be set in the preferences dialog. If unset (empty) the system's default browser is used. If set it specifies the command to execute. Either way, if it fails the user is prompted to correct the pref.

Parameters

uri	The URI to open in the web browser.

Since

0.16

utils_remove_ext_from_filename()

gchar * utils_remove_ext_from_filename

(

const gchar *

filename

)

Removes the extension from filename and return the result in a newly allocated string.

Parameters

filename

The filename to operate on.

Returns

A newly-allocated string, should be freed when no longer needed.

utils_spawn_async()

gboolean utils_spawn_async	(	const gchar *	dir,
		gchar **	argv,
		gchar **	env,
		GSpawnFlags	flags,
		GSpawnChildSetupFunc	child_setup,
		gpointer	user_data,
		GPid *	child_pid,
		GError **	error
	)

Wraps spawn_async(), which see.

Parameters

dir	The child's current working directory, or NULL to inherit parent's.
argv	The child's argument vector.
env	The child's environment, or NULL to inherit parent's.
flags	Ignored.
child_setup	Ignored.
user_data	Ignored.
child_pid	(out) The return location for child process ID, or NULL.
error	The return location for error or NULL.

Returns

TRUE on success, FALSE if an error was set.

utils_spawn_sync()

gboolean utils_spawn_sync	(	const gchar *	dir,
		gchar **	argv,
		gchar **	env,
		GSpawnFlags	flags,
		GSpawnChildSetupFunc	child_setup,
		gpointer	user_data,
		gchar **	std_out,
		gchar **	std_err,
		gint *	exit_status,
		GError **	error
	)

Wraps spawn_sync(), which see.

Parameters

dir	The child's current working directory, or NULL to inherit parent's.
argv	The child's argument vector.
env	The child's environment, or NULL to inherit parent's.
flags	Ignored.
child_setup	Ignored.
user_data	Ignored.
std_out	(out) The return location for child output, or NULL.
std_err	(out) The return location for child error messages, or NULL.
exit_status	(out) The child exit status, as returned by waitpid(), or NULL.
error	The return location for error or NULL.

Returns

TRUE on success, FALSE if an error was set.

utils_str_casecmp()

gint utils_str_casecmp	(	const gchar *	s1,
		const gchar *	s2
	)

A replacement function for g_strncasecmp() to compare strings case-insensitive.

It converts both strings into lowercase using g_utf8_strdown() and then compare both strings using strcmp(). This is not completely accurate regarding locale-specific case sorting rules but seems to be a good compromise between correctness and performance.

The input strings should be in UTF-8 or locale encoding.

Parameters

s1	Pointer to first string or NULL.
s2	Pointer to second string or NULL.

Returns

an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or to be greater than s2.

Since

0.16

utils_str_equal()

gboolean utils_str_equal	(	const gchar *	a,
		const gchar *	b
	)

NULL-safe string comparison.

Returns TRUE if both a and b are NULL or if a and b refer to valid strings which are equal.

Parameters

a	Pointer to first string or NULL.
b	Pointer to second string or NULL.

Returns

TRUE if a equals b, else FALSE.

utils_str_middle_truncate()

gchar * utils_str_middle_truncate	(	const gchar *	string,
		guint	truncate_length
	)

Truncates the input string to a given length.

Characters are removed from the middle of the string, so the start and the end of string won't change.

Parameters

string	Input string.
truncate_length	The length in characters of the resulting string.

Returns

A copy of string which is truncated to truncate_length characters, should be freed when no longer needed.

Since

0.17

utils_str_remove_chars()

gchar * utils_str_remove_chars	(	gchar *	string,
		const gchar *	chars
	)

Removes characters from a string, in place.

Parameters

string	String to search.
chars	Characters to remove.

Returns

string - return value is only useful when nesting function calls, e.g.:

str = utils_str_remove_chars(g_strdup("f_o_o"), "_"); 

See also

g_strdelimit.

utils_string_replace_all()

guint utils_string_replace_all	(	GString *	haystack,
		const gchar *	needle,
		const gchar *	replace
	)

Replaces all occurrences of needle in haystack with replace.

As of Geany 0.16, replace can match needle, so the following will work:

utils_string_replace_all(text, "\n", "\r\n"); 

Parameters

haystack	The input string to operate on. This string is modified in place.
needle	The string which should be replaced.
replace	The replacement for needle.

Returns

Number of replacements made.

utils_string_replace_first()

guint utils_string_replace_first	(	GString *	haystack,
		const gchar *	needle,
		const gchar *	replace
	)

Replaces only the first occurrence of needle in haystack with replace.

For details, see utils_string_replace_all().

Parameters

haystack	The input string to operate on. This string is modified in place.
needle	The string which should be replaced.
replace	The replacement for needle.

Returns

Number of replacements made.

Since

0.16

utils_strv_shorten_file_list()

gchar ** utils_strv_shorten_file_list	(	gchar **	file_names,
		gssize	file_names_len
	)

Transform file names in a list to be shorter.

This function takes a list of file names (probably with absolute paths), and transforms the paths such that they are short but still unique. This is intended for dialogs which present the file list to the user, where the base name may result in duplicates (showing the full path might be inappropriate).

The algorthm strips the common prefix (e-g. the user's home directory) and replaces the longest common substring with an ellipsis ("...").

Parameters

file_names	The list of strings to process.
file_names_len	The number of strings contained in file_names. Can be -1 if it's terminated by NULL.

Returns

(transfer: full) A newly-allocated array of transformed paths strings, terminated by NULL. Use g_strfreev() to free it.

Since

1.34 (API 239)

utils_write_file()

gint utils_write_file	(	const gchar *	filename,
		const gchar *	text
	)

Writes text into a file named filename.

If the file doesn't exist, it will be created. If it already exists, it will be overwritten.

Warning

Currently, this function uses g_file_replace_contents() to save files which offers a reasonable balence between data safety during save and other factors such as handling symlinks, remote files, or platform- dependent aspects. However, plugins with special requirements should not rely on the exact implementation of this function and should rather implement file saving by themselves.

Parameters

filename	The filename of the file to write, in locale encoding.
text	The text to write into the file.

Returns

0 if the file was successfully written, otherwise the errno of the failed operation is returned.