Geany  dev
Macros | Functions
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. More...
 
#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)
 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)   do setptr(ptr, result) while (0)
 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 strftime(). 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...
 
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...
 
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 g_spawn_async() and internally calls this function on Unix-like systems. 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 g_spawn_sync() and internally calls this function on Unix-like systems. 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...
 
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

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

Parameters
typeType of item.
itempointer to item in array.
arrayGArray to traverse.
#define foreach_c_array (   item,
  array,
  len 
)    for (item = array; item < &array[len]; item++)

Iterates all the items in array using pointers.

Parameters
itempointer to an item in array.
arrayC array to traverse.
lenLength of the array.
#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.
dirGDir 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.
#define foreach_list (   node,
  list 
)    for (node = list; node != NULL; node = node->next)

Iterates all the nodes in list.

Parameters
nodeshould be a (GList*).
listGList to traverse.
#define foreach_ptr_array (   item,
  idx,
  ptr_array 
)
Value:
for (idx = 0, item = ((ptr_array)->len > 0 ? g_ptr_array_index((ptr_array), 0) : NULL); \
idx < (ptr_array)->len; ++idx, item = g_ptr_array_index((ptr_array), idx))

Iterates all the pointers in ptr_array.

Parameters
itempointer in ptr_array.
idxguint index into ptr_array.
ptr_arrayGPtrArray to traverse.
#define foreach_range (   i,
  size 
)    for (i = 0; i < size; i++)

Iterates from 0 to size.

Parameters
iInteger.
sizeNumber of iterations.
Since
Geany 0.20.
#define foreach_slist (   node,
  list 
)    foreach_list(node, list)

Iterates all the nodes in list.

Parameters
nodeshould be a (GSList*).
listGSList to traverse.
#define foreach_str (   char_ptr,
  string 
)    for (char_ptr = string; *char_ptr; char_ptr++)

Iterates through each character in string.

Parameters
char_ptrPointer to character.
stringString to traverse.
Warning
Doesn't include null terminating character.
Since
Geany 0.19.
#define foreach_strv (   str_ptr,
  strv 
)    if (!(strv)) {} else foreach_str(str_ptr, strv)

Iterates a null-terminated string vector.

Parameters
str_ptrgchar** pointer to string element.
strvCan be NULL.
Since
Geany 0.20
#define NZV (   ptr)    (!EMPTY(ptr))
Deprecated:
2013/08 - use !EMPTY() instead.
#define SETPTR (   ptr,
  result 
)    do setptr(ptr, result) 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));
#define setptr (   ptr,
  result 
)
Value:
{\
gpointer setptr_tmp = ptr;\
ptr = result;\
g_free(setptr_tmp);\
}
Deprecated:
2011/11/15 - use SETPTR() instead.
#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

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_varsNULL-terminated array of variable names to exclude.
first_varnameName of the first variable to copy into the new array.
...Key-value pairs of variable names and values, NULL-terminated.
Returns
The new environment array.
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.
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.
gchar* utils_get_date_time ( const gchar *  format,
time_t *  time_to_use 
)

Retrieves a formatted date/time string from strftime().

This function should be preferred to directly calling strftime() since this function works on UTF-8 encoded strings.

Parameters
formatThe format string to pass to strftime(3). See the strftime(3) documentation for details, in UTF-8 encoding.
time_to_useThe 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
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
pathThe path of the directory to scan, in locale encoding.
lengthThe location to store the number of non-NULL data items in the list, unless NULL.
errorThe location for storing a possible error, or NULL.
Returns
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().
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
pathThe path of the directory to scan, in locale encoding.
full_pathWhether to include the full path for each filename in the list. Obviously this will use more memory.
sortWhether to sort alphabetically (UTF-8 safe).
errorThe location for storing a possible error, or NULL.
Returns
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().
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_textUTF-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.
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
configA GKeyFile object.
sectionThe group name to look in for the key.
keyThe key to find.
default_valueThe 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.
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
configA GKeyFile object.
sectionThe group name to look in for the key.
keyThe key to find.
default_valueThe 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.
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
configA GKeyFile object.
sectionThe group name to look in for the key.
keyThe key to find.
default_valueThe 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.
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_textText 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.
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
pathThe path of the directory to create, in locale encoding.
create_parent_dirsWhether to create intermediate parent directories if necessary.
Returns
0 if the directory was successfully created, otherwise the errno of the failed operation is returned.
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 set in the preferences dialog is used. In case that fails or it is unset, the user is asked to correct or fill it.

Parameters
uriThe URI to open in the web browser.
Since
0.16
gchar* utils_remove_ext_from_filename ( const gchar *  filename)

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

Parameters
filenameThe filename to operate on.
Returns
A newly-allocated string, should be freed when no longer needed.
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 g_spawn_async() and internally calls this function on Unix-like systems.

On Win32 platforms, it uses the Windows API.

Parameters
dirThe child's current working directory, or NULL to inherit parent's.
argvThe child's argument vector.
envThe child's environment, or NULL to inherit parent's.
flagsFlags from GSpawnFlags.
child_setupA function to run in the child just before exec().
user_dataThe user data for child_setup.
child_pidThe return location for child process ID, or NULL.
errorThe return location for error or NULL.
Returns
TRUE on success, FALSE if an error was set.
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 g_spawn_sync() and internally calls this function on Unix-like systems.

On Win32 platforms, it uses the Windows API.

Parameters
dirThe child's current working directory, or NULL to inherit parent's.
argvThe child's argument vector.
envThe child's environment, or NULL to inherit parent's.
flagsFlags from GSpawnFlags.
child_setupA function to run in the child just before exec().
user_dataThe user data for child_setup.
std_outThe return location for child output, or NULL.
std_errThe return location for child error messages, or NULL.
exit_statusThe child exit status, as returned by waitpid(), or NULL.
errorThe return location for error or NULL.
Returns
TRUE on success, FALSE if an error was set.
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
s1Pointer to first string or NULL.
s2Pointer 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
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
aPointer to first string or NULL.
bPointer to second string or NULL.
Returns
TRUE if a equals b, else FALSE.
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
stringInput string.
truncate_lengthThe 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
gchar* utils_str_remove_chars ( gchar *  string,
const gchar *  chars 
)

Removes characters from a string, in place.

Parameters
stringString to search.
charsCharacters 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.
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
haystackThe input string to operate on. This string is modified in place.
needleThe string which should be replaced.
replaceThe replacement for needle.
Returns
Number of replacements made.
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
haystackThe input string to operate on. This string is modified in place.
needleThe string which should be replaced.
replaceThe replacement for needle.
Returns
Number of replacements made.
Since
0.16
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
You should use g_file_set_contents() instead if you don't need file permissions and other metadata to be preserved, as that always handles disk exhaustion safely.
Parameters
filenameThe filename of the file to write, in locale encoding.
textThe text to write into the file.
Returns
0 if the file was successfully written, otherwise the errno of the failed operation is returned.