String, time and other various helpers. More...
#include <glib.h>#include <stdbool.h>#include <stdio.h>#include <string.h>
Include dependency graph for utils.h: This graph shows which files directly or indirectly include this file:Go to the source code of this file.
Macros | |
| #define | STR_EMPTY(s) |
| Test if a string is NULL or empty. | |
| #define | STR_FULL(s) |
| Test if a string is non-NULL and not empty. | |
| #define | STR_EQ(a, b) |
| Test if string a and b contain the same chars. | |
| #define | STRN_EQ(a, b, n) |
| Test if string a and b are same up to n chars. | |
| #define | STR_CASEQ(a, b) |
| Test if string a and b are the same case-insensitively. | |
| #define | STR_NN(s) |
| Get a non null string from a possibly null one. | |
| #define | STR_TO(...) |
| Stringify the given expression or macro. | |
| #define | _STR_TO(...) |
| #define | ASSERT_OR_RET(expr, val) |
| Assert that expr evaluates to true, if not return val. | |
| #define | S2US(s) |
| Convert seconds into microseconds. | |
| #define | US2S(s) |
| Convert microseconds into seconds. | |
| #define | BOOL2G(x) |
| Make a gboolean from a boolean value. | |
Functions | |
| char * | string_replace_char (char needle, char replacement, char *haystack) |
Replaces all occurrences of the char needle with the char replacement in haystack. | |
| char * | string_replace_at (char *buf, int pos, int len, const char *repl) |
| Replace a substring inside a string with another string. | |
| char * | string_replace_all (const char *needle, const char *replacement, char *haystack) |
| Replace all occurences of a substring. | |
| char * | string_append (char *a, const char *b, const char *sep) |
Append b to string a, then concatenate both with sep (if they are non-empty). | |
| char * | string_strip_quotes (const char *value) |
| Strip quotes from a string, ignoring inner quotes. | |
| void | string_strip_delimited (char *str, char a, char b) |
| Strip content between two delimiter characters. | |
| char ** | string_to_array (const char *string, const char *delimiter) |
| Parse a string into a dynamic array of tokens, using the delimiter string. | |
| char * | string_to_path (char *string) |
| Replace tilde and path-specific values with it's equivalents. | |
| bool | safe_string_to_int (int *in, const char *str) |
| Convert string to int in a safe way. | |
| bool | safe_string_to_long_long (long long *in, const char *str) |
| Same as safe_string_to_int, but then for a long. | |
| bool | safe_string_to_double (double *in, const char *str) |
| Same as safe_string_to_int, but then for a double. | |
| gint64 | string_to_time (const char *string) |
Convert time units (ms, s, m) to the internal gint64 microseconds format. | |
| gint64 | time_monotonic_now (void) |
| Get the current monotonic time. | |
| gint64 | time_now (void) |
| Get the current real time. | |
| gint64 | modification_time (const char *path) |
Get the modification time of the file at path. | |
| const char * | user_get_home (void) |
| Retrieve the HOME directory of the user running dunst. | |
| bool | safe_setenv (const char *key, const char *value) |
| Try to set an environment variable safely. | |
| bool | is_special_section (const char *s) |
| Some sections are handled differently in dunst. | |
| bool | is_deprecated_section (const char *s) |
| This function tells if a section is deprecated. | |
| const char * | get_section_deprecation_message (const char *s) |
| char * | string_strip_brackets (const char *s) |
| Strips a string of it's brackets if the first and last character are a bracket. | |
| int | string_array_length (char **s) |
| Returns the length of a string array, -1 if the input is NULL. | |
| bool | is_readable_file (const char *const path) |
| Check if file is readable. | |
| FILE * | fopen_verbose (const char *const path) |
| Open files verbosely. | |
| void | add_paths_from_env (GPtrArray *arr, char *env_name, char *subdir, char *alternative) |
| Adds the contents of env_name with subdir to the array, interpreting the environment variable as a colon-separated list of paths. | |
| bool | string_is_int (const char *str) |
| Check if string contains digits. | |
| bool | is_like_path (const char *string) |
| Check if the strings looks like a path. | |
Detailed Description
String, time and other various helpers.
- Copyright
- Copyright 2013-2014 Sascha Kruse
- Copyright 2014-2026 Dunst contributors
- License
- BSD-3-Clause
Definition in file utils.h.
Macro Definition Documentation
◆ _STR_TO
◆ ASSERT_OR_RET
| #define ASSERT_OR_RET | ( | expr, | |
| val ) |
◆ BOOL2G
| #define BOOL2G | ( | x | ) |
Make a gboolean from a boolean value.
◆ S2US
| #define S2US | ( | s | ) |
◆ STR_CASEQ
| #define STR_CASEQ | ( | a, | |
| b ) |
◆ STR_EMPTY
| #define STR_EMPTY | ( | s | ) |
◆ STR_EQ
| #define STR_EQ | ( | a, | |
| b ) |
◆ STR_FULL
| #define STR_FULL | ( | s | ) |
Test if a string is non-NULL and not empty.
◆ STR_NN
| #define STR_NN | ( | s | ) |
◆ STR_TO
| #define STR_TO | ( | ... | ) |
◆ STRN_EQ
| #define STRN_EQ | ( | a, | |
| b, | |||
| n ) |
◆ US2S
| #define US2S | ( | s | ) |
Function Documentation
◆ add_paths_from_env()
| void add_paths_from_env | ( | GPtrArray * | arr, |
| char * | env_name, | ||
| char * | subdir, | ||
| char * | alternative ) |
Adds the contents of env_name with subdir to the array, interpreting the environment variable as a colon-separated list of paths.
If the environment variable doesn't exist, alternative is used.
- Parameters
-
arr The array to add to. This array has to be created first with g_ptr_array_new() or a similar function. env_name The name of the environment variable that contains a colon-separated list of paths. subdir The subdirectory to add a the end of each path in env_name alternative A colon-separated list of paths to use as alternative when the environment variable doesn't exits.
◆ fopen_verbose()
| FILE * fopen_verbose | ( | const char *const | path | ) |
Open files verbosely.
This is a wrapper around fopen() and is_readable_file() that does some preliminary checks and sends log messages.
path [in] A char* string representing a filesystem path
- Returns
- The result of the fopen() call.
- Return values
-
NULL if the fopen() call failed or pathdoes not satisfy the conditions of is_readable_file().
◆ get_section_deprecation_message()
| const char * get_section_deprecation_message | ( | const char * | s | ) |
◆ is_deprecated_section()
| bool is_deprecated_section | ( | const char * | s | ) |
◆ is_like_path()
| bool is_like_path | ( | const char * | string | ) |
◆ is_readable_file()
| bool is_readable_file | ( | const char *const | path | ) |
Check if file is readable.
This function checks if path can be resolved and makes sense to try and open, like regular files and FIFOs (named pipes). Finally, a preliminary check is done to see if read permission is granted.
Do not rely too hard on the result, though, since this is racy. A case can be made that these conditions might not be true anymore by the time the file is acutally opened for reading.
Also, no tilde expansion is done. Use the result of string_to_path() for path.
- Parameters
-
path [in] A string representing a path.
- Return values
-
true in case of success. false in case of failure, errno will be set appropriately.
See what intersting stuff can be done with FIFOs
Sets errno if stat() was successful but path [in] does not point to a regular file or FIFO. This just in case someone queries errno which would otherwise indicate success.
◆ is_special_section()
| bool is_special_section | ( | const char * | s | ) |
◆ modification_time()
| gint64 modification_time | ( | const char * | path | ) |
◆ safe_setenv()
| bool safe_setenv | ( | const char * | key, |
| const char * | value ) |
Try to set an environment variable safely.
If an environment variable with name key exists, it will be overwritten. If value is null, key will be set to an empty string.
- Parameters
-
key (nullable) The environment variable to change value (nullable) The value to change it to.
- Returns
- A bool that is true when it succeeds
◆ safe_string_to_double()
| bool safe_string_to_double | ( | double * | in, |
| const char * | str ) |
◆ safe_string_to_int()
| bool safe_string_to_int | ( | int * | in, |
| const char * | str ) |
Convert string to int in a safe way.
When there is an error the int is not changed and false is returned.
- Parameters
-
[out] in The int to save the result in. This is not changed when the parsing does not succeed [in] str The string to parse
- Returns
- a bool if the conversion succeeded
◆ safe_string_to_long_long()
| bool safe_string_to_long_long | ( | long long * | in, |
| const char * | str ) |
◆ string_append()
| char * string_append | ( | char * | a, |
| const char * | b, | ||
| const char * | sep ) |
◆ string_array_length()
| int string_array_length | ( | char ** | s | ) |
◆ string_is_int()
| bool string_is_int | ( | const char * | str | ) |
◆ string_replace_all()
| char * string_replace_all | ( | const char * | needle, |
| const char * | replacement, | ||
| char * | haystack ) |
◆ string_replace_at()
| char * string_replace_at | ( | char * | buf, |
| int | pos, | ||
| int | len, | ||
| const char * | repl ) |
Replace a substring inside a string with another string.
May reallocate memory. Free the result with g_free.
- Parameters
-
buf The string to replace pos The position of the substring to replace len The length of the substring to replace repl The new contents of the substring.
◆ string_replace_char()
| char * string_replace_char | ( | char | needle, |
| char | replacement, | ||
| char * | haystack ) |
Replaces all occurrences of the char needle with the char replacement in haystack.
Does not allocate a new string.
- Parameters
-
needle The char to replace with replacement replacement The char which is the new one haystack (nullable) The string to replace
- Returns
- The exact value of the haystack paramater (to allow nesting)
◆ string_strip_brackets()
| char * string_strip_brackets | ( | const char * | s | ) |
◆ string_strip_delimited()
| void string_strip_delimited | ( | char * | str, |
| char | a, | ||
| char | b ) |
◆ string_strip_quotes()
| char * string_strip_quotes | ( | const char * | value | ) |
◆ string_to_array()
| char ** string_to_array | ( | const char * | string, |
| const char * | delimiter ) |
Parse a string into a dynamic array of tokens, using the delimiter string.
The string is split on the separator character and strips spaces from tokens. The last element of the array is NULL in order to avoid passing around a length variable.
- Parameters
-
string The string to convert to an array delimiter The character that separates list entries
- Returns
- The array of tokens owned by the caller. Free with g_strfreev.
◆ string_to_path()
| char * string_to_path | ( | char * | string | ) |
◆ string_to_time()
| gint64 string_to_time | ( | const char * | string | ) |
◆ time_monotonic_now()
| gint64 time_monotonic_now | ( | void | ) |
Get the current monotonic time.
In contrast to g_get_monotonic_time, this function respects the real monotonic time of the system and counts onwards during system sleep.
- Returns
- A
gint64monotonic time representation
- Note
- On Linux, BOOTTIME is the correct monotonic time, as BOOTTIME counts onwards during sleep. For all other POSIX compliant OSes, MONOTONIC should also count onwards during system sleep.
◆ time_now()
| gint64 time_now | ( | void | ) |
