fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2026-02-06 10:30:39 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

shared/trivial: improve code comments about NMUtilsStrsplitSetFlags flags

Browse source
This commit is contained in:
Thomas Haller 2020-03-27 07:54:47 +01:00
parent 76784e0c97
commit 484d44fc87
2 changed files with 21 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
shared/nm-glib-aux/nm-shared-utils.c
View file

@ -1525,18 +1525,7 @@ _char_lookup_has (const guint8 lookup[static 256],
*
* Note that for @str %NULL and "", this always returns %NULL too. That differs
* from g_strsplit_set(), which would return an empty strv array for "".
*
* Note that g_strsplit_set() returns empty words as well. By default,
* nm_utils_strsplit_set_full() strips all empty tokens (that is, repeated
* delimiters. With %NM_UTILS_STRSPLIT_SET_FLAGS_PRESERVE_EMPTY, empty tokens
* are not removed.
*
* If @flags has %NM_UTILS_STRSPLIT_SET_FLAGS_ALLOW_ESCAPING, delimiters prefixed
* by a backslash are not treated as a separator. Such delimiters and their escape
* character are copied to the current word without unescaping them. In general,
* nm_utils_strsplit_set_full() does not remove any backslash escape characters
* and does not unescaping. It only considers them for skipping to split at
* an escaped delimiter.
* This never returns an empty array.
*
* Returns: %NULL if @str is %NULL or "".
* If @str only contains delimiters and %NM_UTILS_STRSPLIT_SET_FLAGS_PRESERVE_EMPTY
@ -1546,7 +1535,7 @@ _char_lookup_has (const guint8 lookup[static 256],
* The strings to which the result strv array points to are allocated
* after the returned result itself. Don't free the strings themself,
* but free everything with g_free().
* It is however safe and allowed to modify the indiviual strings,
* It is however safe and allowed to modify the individual strings in-place,
* like "g_strstrip((char *) iter[0])".
*/
const char **

19
shared/nm-glib-aux/nm-shared-utils.h
View file

@ -440,7 +440,25 @@ int nm_utils_dbus_path_cmp (const char *dbus_path_a, const char *dbus_path_b);
typedef enum {
NM_UTILS_STRSPLIT_SET_FLAGS_NONE = 0,
/* by default, strsplit will coalesce consecutive delimiters and remove
* them from the result. If this flag is present, empty values are preserved
* and returned.
*
* When combined with %NM_UTILS_STRSPLIT_SET_FLAGS_STRSTRIP, if a value gets
* empty after strstrip(), it also gets removed. */
NM_UTILS_STRSPLIT_SET_FLAGS_PRESERVE_EMPTY = (1u << 0),
/* %NM_UTILS_STRSPLIT_SET_FLAGS_ALLOW_ESCAPING means that delimiters prefixed
* by a backslash are not treated as a separator. Such delimiters and their escape
* character are copied to the current word without unescaping them. In general,
* nm_utils_strsplit_set_full() does not remove any backslash escape characters
* and does no unescaping. It only considers them for skipping to split at
* an escaped delimiter.
*
* If this is combined with (or implied by %NM_UTILS_STRSPLIT_SET_FLAGS_ESCAPED), then
* the backslash escapes are removed from the result.
*/
NM_UTILS_STRSPLIT_SET_FLAGS_ALLOW_ESCAPING = (1u << 1),
/* If flag is set, does the same as g_strstrip() on the returned tokens.
@ -480,6 +498,7 @@ typedef enum {
* need extra care, and then only if they proceed one of the relevant characters.
*/
NM_UTILS_STRSPLIT_SET_FLAGS_ESCAPED = (1u << 3),
} NMUtilsStrsplitSetFlags;
const char **nm_utils_strsplit_set_full (const char *str,