# Interface ICharacterPairMatcher

All Known Implementing Classes:
  `DefaultCharacterPairMatcher`

public interface ICharacterPairMatcher
A character pair matcher finds to a character at a certain document offset the matching peer character. It is the matchers responsibility to define the concepts of "matching" and "peer". The matching process starts at a given offset. Starting of this offset, the matcher chooses a character close to this offset. The anchor defines whether the chosen character is left or right of the initial offset. The matcher then searches for the matching peer character of the chosen character and if it finds one, delivers the minimal region of the document that contains both characters.

In order to provide backward compatibility for clients of `ICharacterPairMatcher`, extension interfaces are used to provide a means of evolution. The following extension interface exists:

- `ICharacterPairMatcherExtension` since version 3.8 introducing the concept of matching peer character and enclosing peer characters for a given selection.

Clients may implement this interface and its extension interface or use the default implementation provided by `DefaultCharacterPairMatcher`.

Since:
  2.1
See Also:
  - `ICharacterPairMatcherExtension`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`LEFT`
Indicates the anchor value "left".
`static final int`
`RIGHT`
Indicates the anchor value "right".

## Method Summary

Modifier and Type
Method
Description
`void`
`clear()`
Clears this pair matcher.
`void`
`dispose()`
Disposes this pair matcher.
`int`
`getAnchor()`
Returns the anchor for the region of the matching peer characters.
`IRegion`
`match(IDocument document, int offset)`
Starting at the given offset, the matcher chooses a character close to this offset.

## Field Details

### RIGHT

static final int RIGHT
Indicates the anchor value "right".

See Also:
  - Constant Field Values

### LEFT

static final int LEFT
Indicates the anchor value "left".

See Also:
  - Constant Field Values

## Method Details

### dispose

void dispose()
Disposes this pair matcher.

### clear

void clear()
Clears this pair matcher. I.e. the matcher throws away all state it might remember and prepares itself for a new call of the `match` method.

### match

IRegion match(IDocument document, int offset)
Starting at the given offset, the matcher chooses a character close to this offset. The matcher then searches for the matching peer character of the chosen character and if it finds one, returns the minimal region of the document that contains both characters.

Since version 3.8 the recommended way for finding matching peers is to use `ICharacterPairMatcherExtension.match(IDocument, int, int)` .

Parameters:
  `document` - the document to work on
  `offset` - the start offset
Returns:
  the minimal region containing the peer characters or `null` if there is no peer character.

### getAnchor

int getAnchor()
Returns the anchor for the region of the matching peer characters. The anchor says whether the character that has been chosen to search for its peer character has been the left or the right character of the pair.

Returns:
  `RIGHT` or `LEFT`