Package org.eclipse.jface.text.source

# Class DefaultCharacterPairMatcher

java.lang.Object
org.eclipse.jface.text.source.DefaultCharacterPairMatcher

All Implemented Interfaces:
  `ICharacterPairMatcher`, `ICharacterPairMatcherExtension`

public class DefaultCharacterPairMatcher extends Object implements ICharacterPairMatcher, ICharacterPairMatcherExtension
A character pair matcher that matches a specified set of character pairs against each other. Only characters that occur in the same partitioning are matched.

Since:
  3.3

## Field Summary

### Fields inherited from interface org.eclipse.jface.text.source.ICharacterPairMatcher

`LEFT, RIGHT`

## Constructor Summary

Constructors
Constructor
Description
`DefaultCharacterPairMatcher(char[] chars)`
Creates a new character pair matcher that matches characters within the default partitioning.
`DefaultCharacterPairMatcher(char[] chars, String partitioning)`
Creates a new character pair matcher that matches the specified characters within the specified partitioning.
`DefaultCharacterPairMatcher(char[] chars, String partitioning, boolean caretEitherSideOfBracket)`
Creates a new character pair matcher that matches the specified characters within the specified partitioning.

## Method Summary

Modifier and Type
Method
Description
`void`
`clear()`
Clears this pair matcher.
`void`
`dispose()`
Disposes this pair matcher.
`IRegion`
`findEnclosingPeerCharacters(IDocument document, int offset, int length)`
Starting at the given selection, the matcher searches for a pair of enclosing peer characters and if it finds one, returns the minimal region of the document that contains the pair.
`int`
`getAnchor()`
Returns the anchor for the region of the matching peer characters.
`boolean`
`isMatchedChar(char ch)`
Checks whether the character is one of the characters matched by the pair matcher.
`boolean`
`isMatchedChar(char ch, IDocument document, int offset)`
Checks whether the character is one of the characters matched by the pair matcher.
`boolean`
`isRecomputationOfEnclosingPairRequired(IDocument document, IRegion currentSelection, IRegion previousSelection)`
Computes whether a client needs to recompute the enclosing pair after a selection change in the document.
`IRegion`
`match(IDocument doc, int offset)`
Starting at the given offset, the matcher chooses a character close to this offset.
`IRegion`
`match(IDocument document, int offset, int length)`
Starting at the given offset (i.e. length 0) or the selected character, the matcher searches for the matching peer character and if it finds one, returns the minimal region of the document that contains both characters.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### DefaultCharacterPairMatcher

public DefaultCharacterPairMatcher(char[] chars, String partitioning)
Creates a new character pair matcher that matches the specified characters within the specified partitioning. The specified list of characters must have the form

> { start, end, start, end, ..., start, end }

For instance:

     char[] chars = new char[] {'(', ')', '{', '}', '[', ']'};
     new DefaultCharacterPairMatcher(chars, ...);

Parameters:
  `chars` - a list of characters
  `partitioning` - the partitioning to match within

### DefaultCharacterPairMatcher

public DefaultCharacterPairMatcher(char[] chars, String partitioning, boolean caretEitherSideOfBracket)
Creates a new character pair matcher that matches the specified characters within the specified partitioning. The specified list of characters must have the form

> { start, end, start, end, ..., start, end }

For instance:

     char[] chars = new char[] {'(', ')', '{', '}', '[', ']'};
     new DefaultCharacterPairMatcher(chars, ...);

Parameters:
  `chars` - a list of characters
  `partitioning` - the partitioning to match within
  `caretEitherSideOfBracket` - controls the matching behavior. When `true`, the matching peer will be found when the caret is placed either before or after a character. When `false`, the matching peer will be found only when the caret is placed after a character.
Since:
  3.8

### DefaultCharacterPairMatcher

public DefaultCharacterPairMatcher(char[] chars)
Creates a new character pair matcher that matches characters within the default partitioning. The specified list of characters must have the form

> { start, end, start, end, ..., start, end }

For instance:

     char[] chars= new char[] { '(', ')', '{', '}', '[', ']' };
     new DefaultCharacterPairMatcher(chars);

Parameters:
  `chars` - a list of characters

## Method Details

### match

public IRegion match(IDocument doc, int offset)
Description copied from interface: `ICharacterPairMatcher`
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)` .

Specified by:
  `match` in interface `ICharacterPairMatcher`
Parameters:
  `doc` - 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.

### match

public IRegion match(IDocument document, int offset, int length)
Description copied from interface: `ICharacterPairMatcherExtension`
Starting at the given offset (i.e. length 0) or the selected character, the matcher searches for the matching peer character and if it finds one, returns the minimal region of the document that contains both characters.

Specified by:
  `match` in interface `ICharacterPairMatcherExtension`
Parameters:
  `document` - the document to work on
  `offset` - the start offset
  `length` - the selection length which can be negative indicating right-to-left selection
Returns:
  the minimal region containing the peer characters or `null` if there is no peer character
Since:
  3.8
See Also:
  - `ICharacterPairMatcherExtension.match(org.eclipse.jface.text.IDocument, int, int)`

### findEnclosingPeerCharacters

public IRegion findEnclosingPeerCharacters(IDocument document, int offset, int length)
Description copied from interface: `ICharacterPairMatcherExtension`
Starting at the given selection, the matcher searches for a pair of enclosing peer characters and if it finds one, returns the minimal region of the document that contains the pair.

Specified by:
  `findEnclosingPeerCharacters` in interface `ICharacterPairMatcherExtension`
Parameters:
  `document` - the document to work on
  `offset` - the start offset
  `length` - the selection length which can be negative indicating right-to-left selection
Returns:
  the minimal region containing the peer characters or `null` if there is no enclosing pair
Since:
  3.8
See Also:
  - `ICharacterPairMatcherExtension.findEnclosingPeerCharacters(org.eclipse.jface.text.IDocument, int, int)`

### isMatchedChar

public boolean isMatchedChar(char ch)
Description copied from interface: `ICharacterPairMatcherExtension`
Checks whether the character is one of the characters matched by the pair matcher.

Specified by:
  `isMatchedChar` in interface `ICharacterPairMatcherExtension`
Parameters:
  `ch` - the character
Returns:
  `true` if the the character is one of the characters matched by the pair matcher, and `false` otherwise
Since:
  3.8
See Also:
  - `ICharacterPairMatcherExtension.isMatchedChar(char)`

### isMatchedChar

public boolean isMatchedChar(char ch, IDocument document, int offset)
Description copied from interface: `ICharacterPairMatcherExtension`
Checks whether the character is one of the characters matched by the pair matcher.

Clients can use this method to handle characters which may have special meaning in some situations. E.g. in Java, '<' is used as an angular bracket and as well as less-than operator.

Specified by:
  `isMatchedChar` in interface `ICharacterPairMatcherExtension`
Parameters:
  `ch` - the character
  `document` - the document
  `offset` - the offset in document
Returns:
  `true` if the the character is one of the characters matched by the pair matcher, and `false` otherwise
Since:
  3.8
See Also:
  - `ICharacterPairMatcherExtension.isMatchedChar(char, org.eclipse.jface.text.IDocument, int)`

### isRecomputationOfEnclosingPairRequired

public boolean isRecomputationOfEnclosingPairRequired(IDocument document, IRegion currentSelection, IRegion previousSelection)
Description copied from interface: `ICharacterPairMatcherExtension`
Computes whether a client needs to recompute the enclosing pair after a selection change in the document.

This is intended to be a quick test to determine whether a re-computation of the enclosing pair is required, as the re-computation after each selection change via a `ICharacterPairMatcherExtension.findEnclosingPeerCharacters(IDocument, int, int)` call can be expensive for some clients.

Specified by:
  `isRecomputationOfEnclosingPairRequired` in interface `ICharacterPairMatcherExtension`
Parameters:
  `document` - the document to work on
  `currentSelection` - the current selection in the document
  `previousSelection` - the previous selection in the document
Returns:
  `true` if the enclosing pair needs to be recomputed, `false` otherwise
Since:
  3.8
See Also:
  - `ICharacterPairMatcherExtension.isRecomputationOfEnclosingPairRequired(org.eclipse.jface.text.IDocument, org.eclipse.jface.text.IRegion, org.eclipse.jface.text.IRegion)`

### getAnchor

public int getAnchor()
Description copied from interface: `ICharacterPairMatcher`
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.

Specified by:
  `getAnchor` in interface `ICharacterPairMatcher`
Returns:
  `RIGHT` or `LEFT`

### dispose

public void dispose()
Description copied from interface: `ICharacterPairMatcher`
Disposes this pair matcher.

Specified by:
  `dispose` in interface `ICharacterPairMatcher`

### clear

public void clear()
Description copied from interface: `ICharacterPairMatcher`
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.

Specified by:
  `clear` in interface `ICharacterPairMatcher`