GLib.MatchInfo¶

Fields¶

None

Methods¶

	`expand_references` (string_to_expand)
	`fetch` (match_num)
	`fetch_all` ()
	`fetch_named` (name)
	`fetch_named_pos` (name)
	`fetch_pos` (match_num)
	`free` ()
	`get_match_count` ()
	`get_regex` ()
	`get_string` ()
	`is_partial_match` ()
	`matches` ()
	`next` ()
	`ref` ()
	`unref` ()

Details¶

class GLib.MatchInfo¶

A GLib.MatchInfo is an opaque struct used to return information about matches.

expand_references(string_to_expand)[source]¶

Parameters:: string_to_expand (str) – the string to expand
Raises:: GLib.Error
Returns:: the expanded string, or None if an error occurred
Return type:: str or None

Returns a new string containing the text in string_to_expand with references and escape sequences expanded. References refer to the last match done with string against regex and have the same syntax used by GLib.Regex.replace().

The string_to_expand must be UTF-8 encoded even if GLib.RegexCompileFlags.RAW was passed to GLib.Regex.new().

The backreferences are extracted from the string passed to the match function, so you cannot call this function after freeing the string.

self may be None in which case string_to_expand must not contain references. For instance “foo\n” does not refer to an actual pattern and ‘\n’ merely will be replaced with \n character, while to expand “\0” (whole match) one needs the result of a match. Use GLib.Regex.check_replacement() to find out whether string_to_expand contains references.

New in version 2.14.

fetch(match_num)[source]¶

Parameters:: match_num (int) – number of the sub expression
Returns:: The matched substring, or None if an error occurred. You have to free the string yourself
Return type:: str or None

Retrieves the text matching the match_num'th capturing parentheses. 0 is the full text of the match, 1 is the first paren set, 2 the second, and so on.

If match_num is a valid sub pattern but it didn’t match anything (e.g. sub pattern 1, matching “b” against “(a)?b”) then an empty string is returned.

If the match was obtained using the DFA algorithm, that is using GLib.Regex.match_all() or GLib.Regex.match_all_full(), the retrieved string is not that of a set of parentheses but that of a matched substring. Substrings are matched in reverse order of length, so 0 is the longest match.

The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string.

New in version 2.14.

fetch_all()[source]¶

Returns:: a None-terminated array of str * pointers. It must be freed using GLib.strfreev(). If the previous match failed None is returned
Return type:: [str]

Bundles up pointers to each of the matching substrings from a match and stores them in an array of str pointers. The first element in the returned array is the match number 0, i.e. the entire matched text.

If a sub pattern didn’t match anything (e.g. sub pattern 1, matching “b” against “(a)?b”) then an empty string is inserted.

If the last match was obtained using the DFA algorithm, that is using GLib.Regex.match_all() or GLib.Regex.match_all_full(), the retrieved strings are not that matched by sets of parentheses but that of the matched substring. Substrings are matched in reverse order of length, so the first one is the longest match.

The strings are fetched from the string passed to the match function, so you cannot call this function after freeing the string.

New in version 2.14.

fetch_named(name)[source]¶

Parameters:: name (str) – name of the subexpression
Returns:: The matched substring, or None if an error occurred. You have to free the string yourself
Return type:: str or None

Retrieves the text matching the capturing parentheses named name.

If name is a valid sub pattern name but it didn’t match anything (e.g. sub pattern “X”, matching “b” against “(?P<X>a)?b”) then an empty string is returned.

The string is fetched from the string passed to the match function, so you cannot call this function after freeing the string.

New in version 2.14.

fetch_named_pos(name)[source]¶

Parameters:

name (str) – name of the subexpression

Returns:

True if the position was fetched, False otherwise. If the position cannot be fetched, start_pos and end_pos are left unchanged.

start_pos:: pointer to location where to store the start position, or None
end_pos:: pointer to location where to store the end position, or None

Return type:

(bool, start_pos: int, end_pos: int)

Retrieves the position in bytes of the capturing parentheses named name.

If name is a valid sub pattern name but it didn’t match anything (e.g. sub pattern “X”, matching “b” against “(?P<X>a)?b”) then start_pos and end_pos are set to -1 and True is returned.

New in version 2.14.

fetch_pos(match_num)[source]¶

Parameters:

match_num (int) – number of the sub expression

Returns:

True if the position was fetched, False otherwise. If the position cannot be fetched, start_pos and end_pos are left unchanged

start_pos:: pointer to location where to store the start position, or None
end_pos:: pointer to location where to store the end position, or None

Return type:

(bool, start_pos: int, end_pos: int)

Retrieves the position in bytes of the match_num'th capturing parentheses. 0 is the full text of the match, 1 is the first paren set, 2 the second, and so on.

If match_num is a valid sub pattern but it didn’t match anything (e.g. sub pattern 1, matching “b” against “(a)?b”) then start_pos and end_pos are set to -1 and True is returned.

If the match was obtained using the DFA algorithm, that is using GLib.Regex.match_all() or GLib.Regex.match_all_full(), the retrieved position is not that of a set of parentheses but that of a matched substring. Substrings are matched in reverse order of length, so 0 is the longest match.

New in version 2.14.

free()[source]¶: If self is not None, calls GLib.MatchInfo.unref(); otherwise does nothing.

New in version 2.14.

get_match_count()[source]¶

Returns:: Number of matched substrings, or -1 if an error occurred
Return type:: int

Retrieves the number of matched substrings (including substring 0, that is the whole matched text), so 1 is returned if the pattern has no substrings in it and 0 is returned if the match failed.

If the last match was obtained using the DFA algorithm, that is using GLib.Regex.match_all() or GLib.Regex.match_all_full(), the retrieved count is not that of the number of capturing parentheses but that of the number of matched substrings.

New in version 2.14.

get_regex()[source]¶

Returns:: GLib.Regex object used in self
Return type:: GLib.Regex

Returns GLib.Regex object used in self. It belongs to Glib and must not be freed. Use GLib.Regex.ref() if you need to keep it after you free self object.

New in version 2.14.

get_string()[source]¶

Returns:: the string searched with self
Return type:: str

Returns the string searched with self. This is the string passed to GLib.Regex.match() or GLib.Regex.replace() so you may not free it before calling this function.

New in version 2.14.

is_partial_match()[source]¶

Returns:: True if the match was partial, False otherwise
Return type:: bool

Usually if the string passed to GLib.Regex.match() matches as far as it goes, but is too short to match the entire pattern, False is returned. There are circumstances where it might be helpful to distinguish this case from other cases in which there is no match.

Consider, for example, an application where a human is required to type in data for a field with specific formatting requirements. An example might be a date in the form ddmmmyy, defined by the pattern “^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$”. If the application sees the user’s keystrokes one by one, and can check that what has been typed so far is potentially valid, it is able to raise an error as soon as a mistake is made.

GLib.Regex supports the concept of partial matching by means of the GLib.RegexMatchFlags.PARTIAL_SOFT and GLib.RegexMatchFlags.PARTIAL_HARD flags. When they are used, the return code for GLib.Regex.match() or GLib.Regex.match_full() is, as usual, True for a complete match, False otherwise. But, when these functions return False, you can check if the match was partial calling GLib.MatchInfo.is_partial_match().

The difference between GLib.RegexMatchFlags.PARTIAL_SOFT and GLib.RegexMatchFlags.PARTIAL_HARD is that when a partial match is encountered with GLib.RegexMatchFlags.PARTIAL_SOFT, matching continues to search for a possible complete match, while with GLib.RegexMatchFlags.PARTIAL_HARD matching stops at the partial match. When both GLib.RegexMatchFlags.PARTIAL_SOFT and GLib.RegexMatchFlags.PARTIAL_HARD are set, the latter takes precedence.

There were formerly some restrictions on the pattern for partial matching. The restrictions no longer apply.

See pcrepartial(3) for more information on partial matching.

New in version 2.14.

matches()[source]¶

Returns:: True if the previous match operation succeeded, False otherwise
Return type:: bool

Returns whether the previous match operation succeeded.

New in version 2.14.

next()[source]¶

Raises:: GLib.Error
Returns:: True is the string matched, False otherwise
Return type:: bool

Scans for the next match using the same parameters of the previous call to GLib.Regex.match_full() or GLib.Regex.match() that returned self.

The match is done on the string passed to the match function, so you cannot free it before calling this function.

New in version 2.14.

ref()[source]¶

Returns:: self
Return type:: GLib.MatchInfo

Increases reference count of self by 1.

New in version 2.30.

unref()[source]¶: Decreases reference count of self by 1. When reference count drops to zero, it frees all the memory associated with the match_info structure.

New in version 2.30.