SC_STATUS_OUTSIDE_DOCUMENT

[Neil]

A new error status SC_STATUS_OUTSIDE_DOCUMENT has been implemented to indicate when there is an attempt to call Scintilla with a position that is outside the range of the document. It will be used for text insertion operations like SCI_INSERTTEXT and SCI_REPLACETARGET.

Previously, writing outside the document range only caused an assertion to fail in debug builds. This made the failure obvious to developers but did nothing for release builds. At this assertion location, there is also a check that prevented any change to the immediate data which was either the document text or the document styles.

With added features, particularly the change history feature, this could cause incomplete actions and further problems. A failure to add text would not stop change history being modified which could cause change history to lose synchronization with the document text.

Insertions are now checked earlier in processing to avoid incomplete actions. The main bottle-neck method Document::InsertString checks the position. The handlers for the most popular text insertion APIs SCI_INSERTTEXT and SCI_REPLACETARGET also check the position earlier which can help find the precise location and circumstances of failures.

For debug builds, checking first asserts the position is inside the document to make the problem clear inside a debugger. Then, for all builds, a Failure exception is thrown when the position is outside the document. This is a new type that is caught at the end of API handling to set the errorStatus field. Externally maintained platform layers should catch the Failure type to set the new SC_STATUS_OUTSIDE_DOCUMENT. Existing code is likely to catch anything (...) and set the status only to SC_STATUS_FAILURE.

Applications can use the direct status function instead of the direct function to efficiently retrieve the status after every call to Scintilla. It can be clearer to channel all API calls through an application method that sets its own error flag or throws its own exception.

See https://scintilla.org/ScintillaDoc.html#SCI_GETDIRECTSTATUSFUNCTION

This addition was motivated by a Notepad++ issue where the cause wasn't clear and may only be seen later with a hang when displaying change history.

https://github.com/notepad-plus-plus/notepad-plus-plus/issues/17915

A potential problem with this addition is that it may make bugs less visible by continuing to run with erroneous data. The above Notepad++ issue might not have been treated as seriously if there hadn't been a hang. Overall, I think the balance is positive here.

Neil