#1368 API to match next or previous brace

[Zufu Liu]

With following change in Document::BraceMatch():

- position = NextPosition(position, direction);
+ position = NextPosition(maxReStyle ? maxReStyle : position, direction);

This is useful for application that implement auto completion for braces/parentheses/brackets, though the change might not at right place as maxReStyle is reserved for further use.
Consider following tow cases, after typing left parenthesis, caret is after it, in SCN_CHARADDED:

1. application call BraceMatch(GetCurrentPos() - 1, 0) to find the right parenthesis position rightPos.
2. if it found, then call BraceMatch(rightPos, GetCurrentPos() - 1) to check whether the right parenthesis already matched before typing left parenthesis.
3. application can then decide that, for case 1, right parenthesis can be added; for case 2, right parenthesis is not needed.

// case 1
( ... (  ... )
       ^

// case 2
 (     ....)
  ^

[Neil Hodgson]

BraceMatch checks that styles match in order to prevent matching unbalanced braces inside strings or literals. When checking beyond the valid styles, any style is considered matching but this may be incorrect, so maxReStyle is for extending styling further. It just hasn't been implemented as it is low priority.

The proposed change to the second argument is dificult to explain so should be a distinct API.

[Zufu Liu]

How about:

fun position BraceMatchInTarget=(position pos, int maxReStyle)

It's same as BraceMatch, except that only finds matching brace in target range (inclusive like SearchInTarget?), through the brace position pos it self may not in target range.
BraceMatch can be treated as BraceMatchInTarget with whole document target.

[Neil Hodgson]

BraceMatchInTarget is easier to understand.

It may be better to go back to your motivation here: the task is to work out the matching state prior to the character insertion. Perhaps a more direct implementation would be BraceMatch(position, ignoring: insertionPosition).

Its not much use adding APIs that won't be used when its not clear why you would want to use them.

[Zufu Liu]

Both approach does not work: after typing left parenthesis, endStyled is set to GetCurrentPos() - 1, so BraceMatch() returns a random position for first matching right parenthesis regardless of the style.

[Neil Hodgson]

Its likely you can force styling with SCI_COLOURISE inside your SCN_CHARADDED.

[Zufu Liu]

How about BraceMatchNext=(position, startPosition), similar to BraceMatch, but set the explicit start position instead of the implicitly next position position ± 1.

[Neil Hodgson]

OK.

[Zufu Liu]

Added a implementation, changed Document::BraceMatch() into:

Sci::Position BraceMatch(Sci::Position position, Sci::Position maxReStyle, Sci::Position startPos, bool useStartPos) noexcept;

[Neil Hodgson]

Committed as [a2ce85].