:right-sidebar: True MatchInfo =================================================================== .. currentmodule:: gi.repository.GLib .. class:: MatchInfo(*args, **kwargs) :no-contents-entry: A GMatchInfo is an opaque struct used to return information about matches. Methods ------- .. rst-class:: interim-class .. class:: MatchInfo :no-index: .. method:: expand_references(string_to_expand: str) -> str | 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 :func:`~gi.repository.GLib.Regex.replace`. The ``string_to_expand`` must be UTF-8 encoded even if :const:`~gi.repository.GLib.RegexCompileFlags.RAW` was passed to :func:`~gi.repository.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. ``match_info`` may be :const:`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 :func:`~gi.repository.GLib.Regex.check_replacement` to find out whether ``string_to_expand`` contains references. .. versionadded:: 2.14 :param string_to_expand: the string to expand .. method:: fetch(match_num: int) -> str | 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 :func:`~gi.repository.GLib.Regex.match_all` or :func:`~gi.repository.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. .. versionadded:: 2.14 :param match_num: number of the sub expression .. method:: fetch_all() -> list[str] Bundles up pointers to each of the matching substrings from a match and stores them in an array of gchar 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 :func:`~gi.repository.GLib.Regex.match_all` or :func:`~gi.repository.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. .. versionadded:: 2.14 .. method:: fetch_named(name: str) -> str | 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 ``"(?Pa)?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. .. versionadded:: 2.14 :param name: name of the subexpression .. method:: fetch_named_pos(name: str) -> ~typing.Tuple[bool, int, 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 ``"(?Pa)?b"``\) then ``start_pos`` and ``end_pos`` are set to -1 and :const:`True` is returned. .. versionadded:: 2.14 :param name: name of the subexpression .. method:: fetch_pos(match_num: int) -> ~typing.Tuple[bool, int, 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 :const:`True` is returned. If the match was obtained using the DFA algorithm, that is using :func:`~gi.repository.GLib.Regex.match_all` or :func:`~gi.repository.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. .. versionadded:: 2.14 :param match_num: number of the sub expression .. method:: free() -> None If ``match_info`` is not :const:`None`, calls :func:`~gi.repository.GLib.MatchInfo.unref`; otherwise does nothing. .. versionadded:: 2.14 .. method:: get_match_count() -> 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 :func:`~gi.repository.GLib.Regex.match_all` or :func:`~gi.repository.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. .. versionadded:: 2.14 .. method:: get_regex() -> ~gi.repository.GLib.Regex Returns :obj:`~gi.repository.GLib.Regex` object used in ``match_info``\. It belongs to Glib and must not be freed. Use :func:`~gi.repository.GLib.Regex.ref` if you need to keep it after you free ``match_info`` object. .. versionadded:: 2.14 .. method:: get_string() -> str Returns the string searched with ``match_info``\. This is the string passed to :func:`~gi.repository.GLib.Regex.match` or :func:`~gi.repository.GLib.Regex.replace` so you may not free it before calling this function. .. versionadded:: 2.14 .. method:: is_partial_match() -> bool Usually if the string passed to g_regex_match\*() matches as far as it goes, but is too short to match the entire pattern, :const:`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. GRegex supports the concept of partial matching by means of the :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_SOFT` and :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_HARD` flags. When they are used, the return code for :func:`~gi.repository.GLib.Regex.match` or :func:`~gi.repository.GLib.Regex.match_full` is, as usual, :const:`True` for a complete match, :const:`False` otherwise. But, when these functions return :const:`False`, you can check if the match was partial calling :func:`~gi.repository.GLib.MatchInfo.is_partial_match`. The difference between :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_SOFT` and :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_HARD` is that when a partial match is encountered with :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_SOFT`, matching continues to search for a possible complete match, while with :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_HARD` matching stops at the partial match. When both :const:`~gi.repository.GLib.RegexMatchFlags.PARTIAL_SOFT` and :const:`~gi.repository.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. .. versionadded:: 2.14 .. method:: matches() -> bool Returns whether the previous match operation succeeded. .. versionadded:: 2.14 .. method:: next() -> bool Scans for the next match using the same parameters of the previous call to :func:`~gi.repository.GLib.Regex.match_full` or :func:`~gi.repository.GLib.Regex.match` that returned ``match_info``\. The match is done on the string passed to the match function, so you cannot free it before calling this function. .. versionadded:: 2.14