luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 05:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Break gtk-doc stanzas into paragraphs

Browse Source 
Keep the first paragraph short, to act as a summary.
This commit is contained in:
Emmanuele Bassi 2021-08-02 16:00:12 +01:00
parent 4bbe7912a1
commit bed2da6cc2
13 changed files with 169 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
glib/gasyncqueue.c
View File

@ -88,9 +88,9 @@
/**
* GAsyncQueue:
*
* The GAsyncQueue struct is an opaque data structure which represents
* an asynchronous queue. It should only be accessed through the
* g_async_queue_* functions.
* An opaque data structure which represents an asynchronous queue.
*
* It should only be accessed through the `g_async_queue_*` functions.
*/
struct _GAsyncQueue
{

4
glib/gbookmarkfile.h
View File

@ -33,6 +33,7 @@ G_BEGIN_DECLS
* G_BOOKMARK_FILE_ERROR:
*
* Error domain for bookmark file parsing.
*
* Errors in this domain will be from the #GBookmarkFileError
* enumeration. See #GError for information on error domains.
*/
@ -72,8 +73,7 @@ GQuark g_bookmark_file_error_quark (void);
/**
* GBookmarkFile:
*
* The `GBookmarkFile` structure contains only
* private data and should not be directly accessed.
* An opaque data structure representing a set of bookmarks.
*/
typedef struct _GBookmarkFile GBookmarkFile;

1
glib/gchecksum.h
View File

@ -56,6 +56,7 @@ typedef enum {
* GChecksum:
*
* An opaque structure representing a checksumming operation.
*
* To create a new GChecksum, use g_checksum_new(). To free
* a GChecksum, use g_checksum_free().
*

6
glib/gdataset.c
View File

@ -121,9 +121,9 @@
/**
* GData:
*
* The #GData struct is an opaque data structure to represent a
* [Keyed Data List][glib-Keyed-Data-Lists]. It should only be
* accessed via the following functions.
* An opaque data structure that represents a keyed data list.
*
* See also: [Keyed data lists][glib-Keyed-Data-Lists].
**/
/**

3
glib/gdatetime.h
View File

@ -89,8 +89,7 @@ typedef gint64 GTimeSpan;
/**
* GDateTime:
*
* `GDateTime` is an opaque structure whose members
* cannot be accessed directly.
* An opaque structure that represents a date and time, including a time zone.
*
* Since: 2.26
*/

5
glib/gfileutils.c
View File

@ -502,15 +502,16 @@ G_DEFINE_QUARK (g-file-error-quark, g_file_error)
* @err_no: an "errno" value
*
* Gets a #GFileError constant based on the passed-in @err_no.
*
* For example, if you pass in `EEXIST` this function returns
* #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
* %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
* assume that all #GFileError values will exist.
*
* Normally a #GFileError value goes into a #GError returned
* from a function that manipulates files. So you would use
* g_file_error_from_errno() when constructing a #GError.
*
* Returns: #GFileError corresponding to the given @errno
* Returns: #GFileError corresponding to the given @err_no
**/
GFileError
g_file_error_from_errno (gint err_no)

24
glib/gfileutils.h
View File

@ -75,21 +75,21 @@ typedef enum
/**
* GFileSetContentsFlags:
* @G_FILE_SET_CONTENTS_NONE: No guarantees about file consistency or durability.
* The most dangerous setting, which is slightly faster than other settings.
* The most dangerous setting, which is slightly faster than other settings.
* @G_FILE_SET_CONTENTS_CONSISTENT: Guarantee file consistency: after a crash,
* either the old version of the file or the new version of the file will be
* available, but not a mixture. On Unix systems this equates to an `fsync()`
* on the file and use of an atomic `rename()` of the new version of the file
* over the old.
* either the old version of the file or the new version of the file will be
* available, but not a mixture. On Unix systems this equates to an `fsync()`
* on the file and use of an atomic `rename()` of the new version of the file
* over the old.
* @G_FILE_SET_CONTENTS_DURABLE: Guarantee file durability: after a crash, the
* new version of the file will be available. On Unix systems this equates to
* an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
* the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
* directory containing the file after calling `rename()`.
* new version of the file will be available. On Unix systems this equates to
* an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
* the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
* directory containing the file after calling `rename()`.
* @G_FILE_SET_CONTENTS_ONLY_EXISTING: Only apply consistency and durability
* guarantees if the file already exists. This may speed up file operations
* if the file doesn’t currently exist, but may result in a corrupted version
* of the new file if the system crashes while writing it.
* guarantees if the file already exists. This may speed up file operations
* if the file doesn’t currently exist, but may result in a corrupted version
* of the new file if the system crashes while writing it.
*
* Flags to pass to g_file_set_contents_full() to affect its safety and
* performance.

3
glib/gmessages.h
View File

@ -188,7 +188,8 @@ struct _GLogField
* chained and fall back to simpler handlers in case of failure.
*
* Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
* %G_LOG_WRITER_UNHANDLED otherwise
* %G_LOG_WRITER_UNHANDLED otherwise
*
* Since: 2.50
*/
typedef GLogWriterOutput (*GLogWriterFunc) (GLogLevelFlags log_level,

78
glib/gshell.c
View File

@ -48,9 +48,11 @@
/**
* G_SHELL_ERROR:
*
* Error domain for shell functions. Errors in this domain will be from
* the #GShellError enumeration. See #GError for information on error
* domains.
* Error domain for shell functions.
*
* Errors in this domain will be from the #GShellError enumeration.
*
* See #GError for information on error domains.
**/
/**
@ -191,13 +193,17 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
* @unquoted_string: (type filename): a literal string
*
* Quotes a string so that the shell (/bin/sh) will interpret the
* quoted string to mean @unquoted_string. If you pass a filename to
* the shell, for example, you should first quote it with this
* function. The return value must be freed with g_free(). The
* quoting style used is undefined (single or double quotes may be
* quoted string to mean @unquoted_string.
*
* If you pass a filename to the shell, for example, you should first
* quote it with this function.
*
* The return value must be freed with g_free().
*
* The quoting style used is undefined (single or double quotes may be
* used).
*
* Returns: (type filename): quoted string
* Returns: (type filename) (transfer full): quoted string
**/
gchar*
g_shell_quote (const gchar *unquoted_string)
@ -241,27 +247,33 @@ g_shell_quote (const gchar *unquoted_string)
* @quoted_string: (type filename): shell-quoted string
* @error: error return location or NULL
*
* Unquotes a string as the shell (/bin/sh) would. Only handles
* quotes; if a string contains file globs, arithmetic operators,
* variables, backticks, redirections, or other special-to-the-shell
* features, the result will be different from the result a real shell
* would produce (the variables, backticks, etc. will be passed
* through literally instead of being expanded). This function is
* guaranteed to succeed if applied to the result of
* Unquotes a string as the shell (/bin/sh) would.
*
* This function only handles quotes; if a string contains file globs,
* arithmetic operators, variables, backticks, redirections, or other
* special-to-the-shell features, the result will be different from the
* result a real shell would produce (the variables, backticks, etc.
* will be passed through literally instead of being expanded).
*
* This function is guaranteed to succeed if applied to the result of
* g_shell_quote(). If it fails, it returns %NULL and sets the
* error. The @quoted_string need not actually contain quoted or
* escaped text; g_shell_unquote() simply goes through the string and
* unquotes/unescapes anything that the shell would. Both single and
* double quotes are handled, as are escapes including escaped
* newlines. The return value must be freed with g_free(). Possible
* errors are in the #G_SHELL_ERROR domain.
* error.
*
* The @quoted_string need not actually contain quoted or escaped text;
* g_shell_unquote() simply goes through the string and unquotes/unescapes
* anything that the shell would. Both single and double quotes are
* handled, as are escapes including escaped newlines.
*
* The return value must be freed with g_free().
*
* Possible errors are in the %G_SHELL_ERROR domain.
*
* Shell quoting rules are a bit strange. Single quotes preserve the
* literal string exactly. escape sequences are not allowed; not even
* \' - if you want a ' in the quoted text, you have to do something
* like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
* be escaped with backslash. Otherwise double quotes preserve things
* literally.
* `\'` - if you want a `'` in the quoted text, you have to do something
* like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and
* newline to be escaped with backslash. Otherwise double quotes
* preserve things literally.
*
* Returns: (type filename): an unquoted string
**/
@ -625,12 +637,16 @@ tokenize_command_line (const gchar *command_line,
* Parses a command line into an argument vector, in much the same way
* the shell would, but without many of the expansions the shell would
* perform (variable expansion, globs, operators, filename expansion,
* etc. are not supported). The results are defined to be the same as
* those you would get from a UNIX98 /bin/sh, as long as the input
* contains none of the unsupported shell expansions. If the input
* does contain such expansions, they are passed through
* literally. Possible errors are those from the #G_SHELL_ERROR
* domain. Free the returned vector with g_strfreev().
* etc. are not supported).
*
* The results are defined to be the same as those you would get from
* a UNIX98 `/bin/sh`, as long as the input contains none of the
* unsupported shell expansions. If the input does contain such expansions,
* they are passed through literally.
*
* Possible errors are those from the %G_SHELL_ERROR domain.
*
* Free the returned vector with g_strfreev().
*
* Returns: %TRUE on success, %FALSE if error set
**/

15
glib/gslice.c
View File

@ -998,6 +998,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* @next: the field name of the next pointer in @type
*
* Frees a linked list of memory blocks of structure type @type.
*
* The memory blocks must be equal-sized, allocated via
* g_slice_alloc() or g_slice_alloc0() and linked together by
* a @next pointer (similar to #GSList). The name of the
@ -1016,17 +1017,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* @block_size: the number of bytes to allocate
*
* Allocates a block of memory from the slice allocator.
*
* The block address handed out can be expected to be aligned
* to at least 1 * sizeof (void*),
* though in general slices are 2 * sizeof (void*) bytes aligned,
* if a malloc() fallback implementation is used instead,
* the alignment may be reduced in a libc dependent fashion.
* to at least `1 * sizeof (void*)`, though in general slices
* are `2 * sizeof (void*)` bytes aligned; if a `malloc()`
* fallback implementation is used instead, the alignment may
* be reduced in a libc dependent fashion.
*
* Note that the underlying slice allocation mechanism can
* be changed with the [`G_SLICE=always-malloc`][G_SLICE]
* environment variable.
*
* Returns: a pointer to the allocated memory block, which will be %NULL if and
* only if @mem_size is 0
* Returns: a pointer to the allocated memory block, which will
* be %NULL if and only if @mem_size is 0
*
* Since: 2.10
*/

108
glib/gspawn.c
View File

@ -209,6 +209,8 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
* @user_data: (closure): user data for @child_setup
* @child_pid: (out) (optional): return location for child process reference, or %NULL
* @error: return location for error
*
* Executes a child program asynchronously.
*
* See g_spawn_async_with_pipes() for a full description; this function
* simply calls the g_spawn_async_with_pipes() without any pipes.
@ -216,7 +218,7 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
* You should call g_spawn_close_pid() on the returned child process
* reference when you don't need it any more.
*
* If you are writing a GTK+ application, and the program you are spawning is a
* If you are writing a GTK application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext,
* #GAppLaunchContext, or set the %DISPLAY environment variable.
@ -329,6 +331,7 @@ read_data (GString *str,
* @error: return location for error, or %NULL
*
* Executes a child synchronously (waits for the child to exit before returning).
*
* All output from the child is stored in @standard_output and @standard_error,
* if those parameters are non-%NULL. Note that you must set the
* %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
@ -665,52 +668,53 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @error: return location for error
*
* Executes a child program asynchronously (your program will not
* block waiting for the child to exit). The child program is
* specified by the only argument that must be provided, @argv.
* @argv should be a %NULL-terminated array of strings, to be passed
* as the argument vector for the child. The first string in @argv
* is of course the name of the program to execute. By default, the
* name of the program must be a full path. If @flags contains the
* %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
* used to search for the executable. If @flags contains the
* %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
* @envp is used to search for the executable. If both the
* %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
* are set, the `PATH` variable from @envp takes precedence over
* the environment variable.
* block waiting for the child to exit).
*
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
* used, then the program will be run from the current directory (or
* @working_directory, if specified); this might be unexpected or even
* The child program is specified by the only argument that must be
* provided, @argv. @argv should be a %NULL-terminated array of strings,
* to be passed as the argument vector for the child. The first string
* in @argv is of course the name of the program to execute. By default,
* the name of the program must be a full path. If @flags contains the
* %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
* search for the executable. If @flags contains the
* %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
* is used to search for the executable. If both the
* %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
* set, the `PATH` variable from @envp takes precedence over the
* environment variable.
*
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag
* is not used, then the program will be run from the current directory
* (or @working_directory, if specified); this might be unexpected or even
* dangerous in some cases when the current directory is world-writable.
*
* On Windows, note that all the string or string vector arguments to
* this function and the other g_spawn*() functions are in UTF-8, the
* this function and the other `g_spawn*()` functions are in UTF-8, the
* GLib file name encoding. Unicode characters that are not part of
* the system codepage passed in these arguments will be correctly
* available in the spawned program only if it uses wide character API
* to retrieve its command line. For C programs built with Microsoft's
* tools it is enough to make the program have a wmain() instead of
* main(). wmain() has a wide character argument vector as parameter.
* tools it is enough to make the program have a `wmain()` instead of
* `main()`. `wmain()` has a wide character argument vector as parameter.
*
* At least currently, mingw doesn't support wmain(), so if you use
* At least currently, mingw doesn't support `wmain()`, so if you use
* mingw to develop the spawned program, it should call
* g_win32_get_command_line() to get arguments in UTF-8.
*
* On Windows the low-level child process creation API CreateProcess()
* On Windows the low-level child process creation API `CreateProcess()`
* doesn't use argument vectors, but a command line. The C runtime
* library's spawn*() family of functions (which g_spawn_async_with_pipes()
* library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
* eventually calls) paste the argument vector elements together into
* a command line, and the C runtime startup code does a corresponding
* reconstruction of an argument vector from the command line, to be
* passed to main(). Complications arise when you have argument vector
* passed to `main()`. Complications arise when you have argument vector
* elements that contain spaces or double quotes. The `spawn*()` functions
* don't do any quoting or escaping, but on the other hand the startup
* code does do unquoting and unescaping in order to enable receiving
* arguments with embedded spaces or double quotes. To work around this
* asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
* argument vector elements that need it before calling the C runtime
* spawn() function.
* `spawn()` function.
*
* The returned @child_pid on Windows is a handle to the child
* process, not its identifier. Process handles and process
@ -729,13 +733,13 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* free resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling
* the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned
* is equivalent to calling `CloseHandle()` on the process handle returned
* in @child_pid). See g_child_watch_add().
*
* Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
* closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
* other open file descriptors will be inherited by the child; otherwise all
* descriptors except stdin/stdout/stderr will be closed before calling exec()
* descriptors except stdin/stdout/stderr will be closed before calling `exec()`
* in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
* absolute path, it will be looked for in the `PATH` environment
* variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
@ -776,25 +780,25 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @child_setup and @user_data are a function and user data. On POSIX
* platforms, the function is called in the child after GLib has
* performed all the setup it plans to perform (including creating
* pipes, closing file descriptors, etc.) but before calling exec().
* That is, @child_setup is called just before calling exec() in the
* pipes, closing file descriptors, etc.) but before calling `exec()`.
* That is, @child_setup is called just before calling `exec()` in the
* child. Obviously actions taken in this function will only affect
* the child, not the parent.
*
* On Windows, there is no separate fork() and exec() functionality.
* On Windows, there is no separate `fork()` and `exec()` functionality.
* Child processes are created and run with a single API call,
* CreateProcess(). There is no sensible thing @child_setup
* `CreateProcess()`. There is no sensible thing @child_setup
* could be used for on Windows so it is ignored and not called.
*
* If non-%NULL, @child_pid will on Unix be filled with the child's
* process ID. You can use the process ID to send signals to the child,
* or to use g_child_watch_add() (or waitpid()) if you specified the
* or to use g_child_watch_add() (or `waitpid()`) if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
* filled with a handle to the child process only if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
* process using the Win32 API, for example wait for its termination
* with the WaitFor*() functions, or examine its exit code with
* GetExitCodeProcess(). You should close the handle with CloseHandle()
* with the `WaitFor*()` functions, or examine its exit code with
* `GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
* or g_spawn_close_pid() when you no longer need it.
*
* If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
@ -818,7 +822,7 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @error can be %NULL to ignore errors, or non-%NULL to report errors.
* If an error is set, the function returns %FALSE. Errors are reported
* even if they occur in the child (for example if the executable in
* @argv[0] is not found). Typically the `message` field of returned
* `@argv[0]` is not found). Typically the `message` field of returned
* errors should be displayed to users. Possible errors are those from
* the #G_SPAWN_ERROR domain.
*
@ -829,7 +833,7 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* process reference must be closed using g_spawn_close_pid().
*
* On modern UNIX platforms, GLib can use an efficient process launching
* codepath driven internally by posix_spawn(). This has the advantage of
* codepath driven internally by `posix_spawn()`. This has the advantage of
* avoiding the fork-time performance costs of cloning the parent process
* address space, and avoiding associated memory overcommit checks that are
* not relevant in the context of immediately executing a distinct process.
@ -841,9 +845,11 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
* 4. @working_directory is %NULL
* 5. @child_setup is %NULL
* 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
* 6. The program is of a recognised binary format, or has a shebang.
* Otherwise, GLib will have to execute the program through the
* shell, which is not done using the optimized codepath.
*
* If you are writing a GTK+ application, and the program you are spawning is a
* If you are writing a GTK application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext,
* #GAppLaunchContext, or set the `DISPLAY` environment variable.
@ -925,6 +931,8 @@ g_spawn_async_with_pipes_and_fds (const gchar *working_directory,
* @stderr_fd: file descriptor to use for child's stderr, or `-1`
* @error: return location for error
*
* Executes a child program asynchronously.
*
* Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
* so no FD assignments are used.
*
@ -986,12 +994,17 @@ g_spawn_async_with_fds (const gchar *working_directory,
* @error: return location for errors
*
* A simple version of g_spawn_sync() with little-used parameters
* removed, taking a command line instead of an argument vector. See
* g_spawn_sync() for full details. @command_line will be parsed by
* g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
* is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
* implications, so consider using g_spawn_sync() directly if
* appropriate. Possible errors are those from g_spawn_sync() and those
* removed, taking a command line instead of an argument vector.
*
* See g_spawn_sync() for full details.
*
* The @command_line argument will be parsed by g_shell_parse_argv().
*
* Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
* Note that %G_SPAWN_SEARCH_PATH can have security implications, so
* consider using g_spawn_sync() directly if appropriate.
*
* Possible errors are those from g_spawn_sync() and those
* from g_shell_parse_argv().
*
* If @wait_status is non-%NULL, the platform-specific status of
@ -1050,8 +1063,9 @@ g_spawn_command_line_sync (const gchar *command_line,
* @error: return location for errors
*
* A simple version of g_spawn_async() that parses a command line with
* g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
* command line in the background. Unlike g_spawn_async(), the
* g_shell_parse_argv() and passes it to g_spawn_async().
*
* Runs a command line in the background. Unlike g_spawn_async(), the
* %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
* that %G_SPAWN_SEARCH_PATH can have security implications, so
* consider using g_spawn_async() directly if appropriate. Possible
@ -1134,7 +1148,7 @@ g_spawn_command_line_async (const gchar *command_line,
* functionality, although under a misleading name.
*
* Returns: %TRUE if child exited successfully, %FALSE otherwise (and
* @error will be set)
* @error will be set)
*
* Since: 2.70
*/

25
glib/gstrfuncs.c
View File

@ -2028,22 +2028,26 @@ g_strncasecmp (const gchar *s1,
* @new_delimiter: the new delimiter character
*
* Converts any delimiter characters in @string to @new_delimiter.
*
* Any characters in @string which are found in @delimiters are
* changed to the @new_delimiter character. Modifies @string in place,
* and returns @string itself, not a copy. The return value is to
* allow nesting such as
* and returns @string itself, not a copy.
*
* The return value is to allow nesting such as:
*
* |[<!-- language="C" -->
* g_ascii_strup (g_strdelimit (str, "abc", '?'))
* ]|
*
* In order to modify a copy, you may use `g_strdup()`:
* In order to modify a copy, you may use g_strdup():
*
* |[<!-- language="C" -->
* reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
* ...
* g_free (reformatted);
* ]|
*
* Returns: @string
* Returns: the modified @string
*/
gchar *
g_strdelimit (gchar *string,
@ -2073,21 +2077,24 @@ g_strdelimit (gchar *string,
* @substitutor: replacement character for disallowed bytes
*
* For each character in @string, if the character is not in @valid_chars,
* replaces the character with @substitutor. Modifies @string in place,
* and return @string itself, not a copy. The return value is to allow
* nesting such as
* replaces the character with @substitutor.
*
* Modifies @string in place, and return @string itself, not a copy. The
* return value is to allow nesting such as:
*
* |[<!-- language="C" -->
* g_ascii_strup (g_strcanon (str, "abc", '?'))
* ]|
*
* In order to modify a copy, you may use `g_strdup()`:
* In order to modify a copy, you may use g_strdup():
*
* |[<!-- language="C" -->
* reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
* ...
* g_free (reformatted);
* ]|
*
* Returns: @string
* Returns: the modified @string
*/
gchar *
g_strcanon (gchar *string,

13
glib/gunicode.h
View File

@ -758,10 +758,15 @@ GLIB_VAR const gchar * const g_utf8_skip;
* g_utf8_next_char:
* @p: Pointer to the start of a valid UTF-8 character
*
* Skips to the next character in a UTF-8 string. The string must be
* valid; this macro is as fast as possible, and has no error-checking.
* You would use this macro to iterate over a string character by
* character. The macro returns the start of the next UTF-8 character.
* Skips to the next character in a UTF-8 string.
*
* The string must be valid; this macro is as fast as possible, and has
* no error-checking.
*
* You would use this macro to iterate over a string character by character.
*
* The macro returns the start of the next UTF-8 character.
*
* Before using this macro, use g_utf8_validate() to validate strings
* that may contain invalid UTF-8.
*/