gi-glib-2.0.29: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.GLib.Structs.MatchInfo

Contents

- Exported types
- Methods
  - expandReferences
  - fetch
  - fetchAll
  - fetchNamed
  - fetchNamedPos
  - fetchPos
  - free
  - getMatchCount
  - getRegex
  - getString
  - isPartialMatch
  - matches
  - next
  - ref
  - unref

Description

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

Synopsis

- newtype MatchInfo = MatchInfo (ManagedPtr MatchInfo)
- matchInfoExpandReferences :: (HasCallStack, MonadIO m) => MatchInfo -> Text -> m (Maybe Text)
- matchInfoFetch :: (HasCallStack, MonadIO m) => MatchInfo -> Int32 -> m (Maybe Text)
- matchInfoFetchAll :: (HasCallStack, MonadIO m) => MatchInfo -> m [Text]
- matchInfoFetchNamed :: (HasCallStack, MonadIO m) => MatchInfo -> Text -> m (Maybe Text)
- matchInfoFetchNamedPos :: (HasCallStack, MonadIO m) => MatchInfo -> Text -> m (Bool, Int32, Int32)
- matchInfoFetchPos :: (HasCallStack, MonadIO m) => MatchInfo -> Int32 -> m (Bool, Int32, Int32)
- matchInfoFree :: (HasCallStack, MonadIO m) => MatchInfo -> m ()
- matchInfoGetMatchCount :: (HasCallStack, MonadIO m) => MatchInfo -> m Int32
- matchInfoGetRegex :: (HasCallStack, MonadIO m) => MatchInfo -> m Regex
- matchInfoGetString :: (HasCallStack, MonadIO m) => MatchInfo -> m Text
- matchInfoIsPartialMatch :: (HasCallStack, MonadIO m) => MatchInfo -> m Bool
- matchInfoMatches :: (HasCallStack, MonadIO m) => MatchInfo -> m Bool
- matchInfoNext :: (HasCallStack, MonadIO m) => MatchInfo -> m ()
- matchInfoRef :: (HasCallStack, MonadIO m) => MatchInfo -> m MatchInfo
- matchInfoUnref :: (HasCallStack, MonadIO m) => MatchInfo -> m ()

# Exported types

newtype MatchInfo Source #

Memory-managed wrapper type.

Constructors

MatchInfo (ManagedPtr MatchInfo) |

#### Instances

Instances details

Eq MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo Methods (==) :: MatchInfo -> MatchInfo -> Bool Source # (/=) :: MatchInfo -> MatchInfo -> Bool Source #
GBoxed MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo
ManagedPtrNewtype MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo Methods toManagedPtr :: MatchInfo -> ManagedPtr MatchInfo Source #
TypedObject MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo Methods glibType :: IO GType Source #
HasParentTypes MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo
IsGValue (Maybe MatchInfo) Source # | Convert `MatchInfo` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GLib.Structs.MatchInfo Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe MatchInfo -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe MatchInfo) Source #
type ParentTypes MatchInfo Source # |
Instance details Defined in GI.GLib.Structs.MatchInfo type ParentTypes MatchInfo = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

expandReferences, fetch, fetchAll, fetchNamed, fetchNamedPos, fetchPos, free, isPartialMatch, matches, next, ref, unref.

#### Getters

getMatchCount, getRegex, getString.

#### Setters

None.

## expandReferences

matchInfoExpandReferences Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` or `Nothing`
-> Text | `stringToExpand`: the string to expand
-> m (Maybe Text) | Returns: the expanded string, or `Nothing` if an error occurred (Can throw `GError`)

Returns a new string containing the text in `stringToExpand` with references and escape sequences expanded. References refer to the last match done with `string` against `regex` and have the same syntax used by `regexReplace`.

The `stringToExpand` must be UTF-8 encoded even if `RegexCompileFlagsRaw` was passed to `regexNew`.

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

`matchInfo` may be `Nothing` in which case `stringToExpand` 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 `regexCheckReplacement` to find out whether `stringToExpand` contains references.

Since: 2.14

## fetch

matchInfoFetch Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: `MatchInfo` structure
-> Int32 | `matchNum`: number of the sub expression
-> m (Maybe Text) | Returns: The matched substring, or `Nothing` if an error occurred. You have to free the string yourself

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

If `matchNum` 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 `regexMatchAll` or `regexMatchAllFull`, 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.

Since: 2.14

## fetchAll

matchInfoFetchAll Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` structure
-> m [Text] | Returns: a `Nothing`-terminated array of gchar * pointers. It must be freed using `strfreev`. If the previous match failed `Nothing` is returned

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 `regexMatchAll` or `regexMatchAllFull`, 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.

Since: 2.14

## fetchNamed

matchInfoFetchNamed Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: `MatchInfo` structure
-> Text | `name`: name of the subexpression
-> m (Maybe Text) | Returns: The matched substring, or `Nothing` if an error occurred. You have to free the string yourself

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.

Since: 2.14

## fetchNamedPos

matchInfoFetchNamedPos Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: `MatchInfo` structure
-> Text | `name`: name of the subexpression
-> m (Bool, Int32, Int32) | Returns: `True` if the position was fetched, `False` otherwise. If the position cannot be fetched, `startPos` and `endPos` are left unchanged.

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 `startPos` and `endPos` are set to -1 and `True` is returned.

Since: 2.14

## fetchPos

matchInfoFetchPos Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: `MatchInfo` structure
-> Int32 | `matchNum`: number of the sub expression
-> m (Bool, Int32, Int32) | Returns: `True` if the position was fetched, `False` otherwise. If the position cannot be fetched, `startPos` and `endPos` are left unchanged

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

If `matchNum` is a valid sub pattern but it didn't match anything (e.g. sub pattern 1, matching "b" against "(a)?b") then `startPos` and `endPos` are set to -1 and `True` is returned.

If the match was obtained using the DFA algorithm, that is using `regexMatchAll` or `regexMatchAllFull`, 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.

Since: 2.14

## free

matchInfoFree Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo`, or `Nothing`
-> m () |

If `matchInfo` is not `Nothing`, calls `matchInfoUnref`; otherwise does nothing.

Since: 2.14

## getMatchCount

matchInfoGetMatchCount Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` structure
-> m Int32 | Returns: Number of matched substrings, or -1 if an error occurred

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 `regexMatchAll` or `regexMatchAllFull`, the retrieved count is not that of the number of capturing parentheses but that of the number of matched substrings.

Since: 2.14

## getRegex

matchInfoGetRegex Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo`
-> m Regex | Returns: `Regex` object used in `matchInfo`

Returns `Regex` object used in `matchInfo`. It belongs to Glib and must not be freed. Use `regexRef` if you need to keep it after you free `matchInfo` object.

Since: 2.14

## getString

matchInfoGetString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo`
-> m Text | Returns: the string searched with `matchInfo`

Returns the string searched with `matchInfo`. This is the string passed to `regexMatch` or `regexReplace` so you may not free it before calling this function.

Since: 2.14

## isPartialMatch

matchInfoIsPartialMatch Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` structure
-> m Bool | Returns: `True` if the match was partial, `False` otherwise

Usually if the string passed to g_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.

GRegex supports the concept of partial matching by means of the `RegexMatchFlagsPartialSoft` and `RegexMatchFlagsPartialHard` flags. When they are used, the return code for `regexMatch` or `regexMatchFull` 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 `matchInfoIsPartialMatch`.

The difference between `RegexMatchFlagsPartialSoft` and `RegexMatchFlagsPartialHard` is that when a partial match is encountered with `RegexMatchFlagsPartialSoft`, matching continues to search for a possible complete match, while with `RegexMatchFlagsPartialHard` matching stops at the partial match. When both `RegexMatchFlagsPartialSoft` and `RegexMatchFlagsPartialHard` 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.

Since: 2.14

## matches

matchInfoMatches Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` structure
-> m Bool | Returns: `True` if the previous match operation succeeded, `False` otherwise

Returns whether the previous match operation succeeded.

Since: 2.14

## next

matchInfoNext Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo` structure
-> m () | (Can throw `GError`)

Scans for the next match using the same parameters of the previous call to `regexMatchFull` or `regexMatch` that returned `matchInfo`.

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

Since: 2.14

## ref

matchInfoRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo`
-> m MatchInfo | Returns: `matchInfo`

Increases reference count of `matchInfo` by 1.

Since: 2.30

## unref

matchInfoUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> MatchInfo | `matchInfo`: a `MatchInfo`
-> m () |

Decreases reference count of `matchInfo` by 1. When reference count drops to zero, it frees all the memory associated with the match_info structure.

Since: 2.30