:right-sidebar: True

PatternSpec
===================================================================

.. currentmodule:: gi.repository.GLib





.. class:: PatternSpec(**kwargs)
   :no-contents-entry:






A ``GPatternSpec`` struct is the ‘compiled’ form of a glob-style pattern.

The :obj:`~gi.repository.GLib.pattern_match_simple` and :obj:`~gi.repository.GLib.PatternSpec.match` functions
match a string against a pattern containing ``*`` and ``?`` wildcards with similar
semantics as the standard ``glob()`` function: ``*`` matches an arbitrary,
possibly empty, string, ``?`` matches an arbitrary character.

Note that in contrast to ```glob()`` <man:glob(3)>`__\, the ``/`` character can be
matched by the wildcards, there are no ``[…]`` character ranges and ``*`` and ``?``
can not be escaped to include them literally in a pattern.

When multiple strings must be matched against the same pattern, it is better
to compile the pattern to a :obj:`~gi.repository.GLib.PatternSpec` using
:obj:`~gi.repository.GLib.PatternSpec.new` and use :obj:`~gi.repository.GLib.PatternSpec.match_string`
instead of :obj:`~gi.repository.GLib.pattern_match_simple`\. This avoids the overhead of repeated
pattern compilation.


Constructors
------------

.. rst-class:: interim-class

.. class:: PatternSpec
   :no-index:


   .. classmethod:: new(pattern: str) -> ~gi.repository.GLib.PatternSpec

      Compiles a pattern to a :obj:`~gi.repository.GLib.PatternSpec`\.






      :param pattern: a zero-terminated UTF-8 encoded string








Methods
-------

.. rst-class:: interim-class

.. class:: PatternSpec
   :no-index:


   .. method:: equal(pspec2: ~gi.repository.GLib.PatternSpec) -> bool

      Compares two compiled pattern specs and returns whether they will
      match the same set of strings.






      :param pspec2: another :obj:`~gi.repository.GLib.PatternSpec`




   .. method:: free() -> None

      Frees the memory allocated for the :obj:`~gi.repository.GLib.PatternSpec`\.









   .. method:: match(string_length: int, string: str, string_reversed: str | None = None) -> bool

      Matches a string against a compiled pattern.

      Passing the correct
      length of the string given is mandatory. The reversed string can be
      omitted by passing ``NULL``\, this is more efficient if the reversed
      version of the string to be matched is not at hand, as
      :obj:`~gi.repository.GLib.PatternSpec.match` will only construct it if the compiled pattern
      requires reverse matches.

      Note that, if the user code will (possibly) match a string against a
      multitude of patterns containing wildcards, chances are high that
      some patterns will require a reversed string. In this case, it’s
      more efficient to provide the reversed string to avoid multiple
      constructions thereof in the various calls to :obj:`~gi.repository.GLib.PatternSpec.match`\.

      Note also that the reverse of a UTF-8 encoded string can in general
      not be obtained by :obj:`~gi.repository.GLib.strreverse`\. This works only if the string
      does not contain any multibyte characters. GLib offers the
      :obj:`~gi.repository.GLib.utf8_strreverse` function to reverse UTF-8 encoded strings.


      .. versionadded:: 2.70





      :param string_length: the length of ``string`` (in bytes, i.e. ``strlen()``\,
            not :obj:`~gi.repository.GLib.utf8_strlen`\)

      :param string: the UTF-8 encoded string to match

      :param string_reversed: the reverse of ``string``




   .. method:: match_string(string: str) -> bool

      Matches a string against a compiled pattern.

      If the string is to be
      matched against more than one pattern, consider using
      :obj:`~gi.repository.GLib.PatternSpec.match` instead while supplying the reversed string.


      .. versionadded:: 2.70





      :param string: the UTF-8 encoded string to match