luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'gpattern-docs' into 'main'

Browse Source 
gpattern: Port the docs to gi-docgen syntax

See merge request GNOME/glib!4081
This commit is contained in:
Philip Withnall 2024-05-23 09:55:32 +00:00
commit 31c85d3985
1 changed files with 50 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
glib/gpattern.c
View File

@ -33,15 +33,15 @@
/** /**
* GPatternSpec: * GPatternSpec:
* *
* A `GPatternSpec` struct is the 'compiled' form of a glob-style pattern. * A `GPatternSpec` struct is the ‘compiled’ form of a glob-style pattern.
* *
* The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions * The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions
* match a string against a pattern containing '*' and '?' wildcards with similar * match a string against a pattern containing `*` and `?` wildcards with similar
* semantics as the standard `glob()` function: '*' matches an arbitrary, * semantics as the standard `glob()` function: `*` matches an arbitrary,
* possibly empty, string, '?' matches an arbitrary character. * possibly empty, string, `?` matches an arbitrary character.
* *
* Note that in contrast to `glob()`, the '/' character can be matched by * Note that in contrast to [`glob()`](man:glob(3)), the `/` character can be
* the wildcards, there are no '[...]' character ranges and '*' and '?' * matched by the wildcards, there are no `[…]` character ranges and `*` and `?`
* can not be escaped to include them literally in a pattern. * can not be escaped to include them literally in a pattern.
* *
* When multiple strings must be matched against the same pattern, it is better * When multiple strings must be matched against the same pattern, it is better
@ -154,28 +154,30 @@ g_pattern_ph_match (const gchar *match_pattern,
/** /**
* g_pattern_spec_match: * g_pattern_spec_match:
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* @string_length: the length of @string (in bytes, i.e. strlen(), * @string_length: the length of @string (in bytes, i.e. `strlen()`,
* not g_utf8_strlen()) * not [func@GLib.utf8_strlen])
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* @string_reversed: (nullable): the reverse of @string or %NULL * @string_reversed: (nullable): the reverse of @string
* *
* Matches a string against a compiled pattern. Passing the correct * Matches a string against a compiled pattern.
*
* Passing the correct
* length of the string given is mandatory. The reversed string can be * length of the string given is mandatory. The reversed string can be
* omitted by passing %NULL, this is more efficient if the reversed * omitted by passing `NULL`, this is more efficient if the reversed
* version of the string to be matched is not at hand, as * version of the string to be matched is not at hand, as
* g_pattern_match() will only construct it if the compiled pattern * [method@GLib.PatternSpec.match] will only construct it if the compiled pattern
* requires reverse matches. * requires reverse matches.
* *
* Note that, if the user code will (possibly) match a string against a * Note that, if the user code will (possibly) match a string against a
* multitude of patterns containing wildcards, chances are high that * multitude of patterns containing wildcards, chances are high that
* some patterns will require a reversed string. In this case, it's * some patterns will require a reversed string. In this case, it’s
* more efficient to provide the reversed string to avoid multiple * more efficient to provide the reversed string to avoid multiple
* constructions thereof in the various calls to g_pattern_match(). * constructions thereof in the various calls to [method@GLib.PatternSpec.match].
* *
* Note also that the reverse of a UTF-8 encoded string can in general * Note also that the reverse of a UTF-8 encoded string can in general
* not be obtained by g_strreverse(). This works only if the string * not be obtained by [func@GLib.strreverse]. This works only if the string
* does not contain any multibyte characters. GLib offers the * does not contain any multibyte characters. GLib offers the
* g_utf8_strreverse() function to reverse UTF-8 encoded strings. * [func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
* *
@ -237,31 +239,33 @@ g_pattern_spec_match (GPatternSpec *pspec,
/** /**
* g_pattern_match: (skip) * g_pattern_match: (skip)
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* @string_length: the length of @string (in bytes, i.e. strlen(), * @string_length: the length of @string (in bytes, i.e. `strlen()`,
* not g_utf8_strlen()) * not [func@GLib.utf8_strlen])
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* @string_reversed: (nullable): the reverse of @string or %NULL * @string_reversed: (nullable): the reverse of @string
* *
* Matches a string against a compiled pattern. Passing the correct * Matches a string against a compiled pattern.
*
* Passing the correct
* length of the string given is mandatory. The reversed string can be * length of the string given is mandatory. The reversed string can be
* omitted by passing %NULL, this is more efficient if the reversed * omitted by passing `NULL`, this is more efficient if the reversed
* version of the string to be matched is not at hand, as * version of the string to be matched is not at hand, as
* g_pattern_match() will only construct it if the compiled pattern * `g_pattern_match()` will only construct it if the compiled pattern
* requires reverse matches. * requires reverse matches.
* *
* Note that, if the user code will (possibly) match a string against a * Note that, if the user code will (possibly) match a string against a
* multitude of patterns containing wildcards, chances are high that * multitude of patterns containing wildcards, chances are high that
* some patterns will require a reversed string. In this case, it's * some patterns will require a reversed string. In this case, it’s
* more efficient to provide the reversed string to avoid multiple * more efficient to provide the reversed string to avoid multiple
* constructions thereof in the various calls to g_pattern_match(). * constructions thereof in the various calls to `g_pattern_match()`.
* *
* Note also that the reverse of a UTF-8 encoded string can in general * Note also that the reverse of a UTF-8 encoded string can in general
* not be obtained by g_strreverse(). This works only if the string * not be obtained by [func@GLib.strreverse]. This works only if the string
* does not contain any multibyte characters. GLib offers the * does not contain any multibyte characters. GLib offers the
* g_utf8_strreverse() function to reverse UTF-8 encoded strings. * [func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
* Deprecated: 2.70: Use g_pattern_spec_match() instead * Deprecated: 2.70: Use [method@GLib.PatternSpec.match] instead
**/ **/
gboolean gboolean
g_pattern_match (GPatternSpec *pspec, g_pattern_match (GPatternSpec *pspec,
@ -276,9 +280,9 @@ g_pattern_match (GPatternSpec *pspec,
* g_pattern_spec_new: * g_pattern_spec_new:
* @pattern: a zero-terminated UTF-8 encoded string * @pattern: a zero-terminated UTF-8 encoded string
* *
* Compiles a pattern to a #GPatternSpec. * Compiles a pattern to a [type@GLib.PatternSpec].
* *
* Returns: a newly-allocated #GPatternSpec * Returns: (transfer full): a newly-allocated [type@GLib.PatternSpec]
**/ **/
GPatternSpec* GPatternSpec*
g_pattern_spec_new (const gchar *pattern) g_pattern_spec_new (const gchar *pattern)
@ -392,7 +396,7 @@ g_pattern_spec_new (const gchar *pattern)
* g_pattern_spec_copy: * g_pattern_spec_copy:
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* *
* Copies @pspec in a new #GPatternSpec. * Copies @pspec in a new [type@GLib.PatternSpec].
* *
* Returns: (transfer full): a copy of @pspec. * Returns: (transfer full): a copy of @pspec.
* *
@ -416,7 +420,7 @@ g_pattern_spec_copy (GPatternSpec *pspec)
* g_pattern_spec_free: * g_pattern_spec_free:
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* *
* Frees the memory allocated for the #GPatternSpec. * Frees the memory allocated for the [type@GLib.PatternSpec].
**/ **/
void void
g_pattern_spec_free (GPatternSpec *pspec) g_pattern_spec_free (GPatternSpec *pspec)
@ -454,9 +458,11 @@ g_pattern_spec_equal (GPatternSpec *pspec1,
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* *
* Matches a string against a compiled pattern. If the string is to be * Matches a string against a compiled pattern.
*
* If the string is to be
* matched against more than one pattern, consider using * matched against more than one pattern, consider using
* g_pattern_match() instead while supplying the reversed string. * [method@GLib.PatternSpec.match] instead while supplying the reversed string.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
* *
@ -477,12 +483,14 @@ g_pattern_spec_match_string (GPatternSpec *pspec,
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* *
* Matches a string against a compiled pattern. If the string is to be * Matches a string against a compiled pattern.
*
* If the string is to be
* matched against more than one pattern, consider using * matched against more than one pattern, consider using
* g_pattern_match() instead while supplying the reversed string. * [method@GLib.PatternSpec.match] instead while supplying the reversed string.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
* Deprecated: 2.70: Use g_pattern_spec_match_string() instead * Deprecated: 2.70: Use [method@GLib.PatternSpec.match_string] instead
**/ **/
gboolean gboolean
g_pattern_match_string (GPatternSpec *pspec, g_pattern_match_string (GPatternSpec *pspec,
@ -496,10 +504,12 @@ g_pattern_match_string (GPatternSpec *pspec,
* @pattern: the UTF-8 encoded pattern * @pattern: the UTF-8 encoded pattern
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* *
* Matches a string against a pattern given as a string. If this * Matches a string against a pattern given as a string.
* function is to be called in a loop, it's more efficient to compile *
* the pattern once with g_pattern_spec_new() and call * If this
* g_pattern_match_string() repeatedly. * function is to be called in a loop, it’s more efficient to compile
* the pattern once with [ctor@GLib.PatternSpec.new] and call
* [method@GLib.PatternSpec.match_string] repeatedly.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
**/ **/