SC_STATUS_OUTSIDE_DOCUMENT

------=_Part_138110_1814789555.1776909214737
Content-Type: multipart/alternative; 
	boundary="----=_Part_138111_1673605737.1776909214737"

------=_Part_138111_1673605737.1776909214737
Content-Type: text/plain; charset="UTF-8"

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

-- 
You received this message because you are subscribed to the Google Groups "scintilla-interest" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To view this discussion visit https://groups.google.com/d/msgid/scintilla-interest/dcb4ce29-39ef-4941-8120-7a08f2518583n%40googlegroups.com.

------=_Part_138111_1673605737.1776909214737
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

A new error status=C2=A0SC_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 oper=
ations like=C2=A0SCI_INSERTTEXT and=C2=A0SCI_REPLACETARGET.<div><br /></div=
><div>Previously, writing outside the document range only caused an asserti=
on 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 th=
e document text or the document styles.</div><div><br /></div><div>With add=
ed features, particularly the change history feature, this could cause inco=
mplete actions and further problems. A failure to add text would not stop c=
hange history being modified which could cause change history to lose synch=
ronization with the document text.</div><div><br /></div><div>Insertions ar=
e now checked earlier in processing to avoid incomplete actions. The main b=
ottle-neck method=C2=A0Document::InsertString checks the position. The hand=
lers for the most popular text insertion APIs SCI_INSERTTEXT and SCI_REPLAC=
ETARGET also check the position earlier which can help find the precise loc=
ation and circumstances of failures.</div><div><br /></div><div>For debug b=
uilds, checking first asserts the position is inside the document to make t=
he problem clear inside a debugger. Then, for all builds, a Failure excepti=
on 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. Ext=
ernally maintained platform layers should catch the Failure type to set the=
 new=C2=A0SC_STATUS_OUTSIDE_DOCUMENT. Existing code is likely to catch anyt=
hing (...) and set the status only to SC_STATUS_FAILURE.</div><div><br /></=
div><div>Applications can use the direct status function instead of the dir=
ect function to efficiently retrieve the status after every call to Scintil=
la. It can be clearer to channel all API calls through an application metho=
d that sets its own error flag or throws its own exception.</div><div>See=
=C2=A0https://scintilla.org/ScintillaDoc.html#SCI_GETDIRECTSTATUSFUNCTION</=
div><div><br /></div><div>This addition was motivated by a Notepad++ issue =
where the cause wasn't clear and may only be seen later with a hang when di=
splaying change history.</div><div>https://github.com/notepad-plus-plus/not=
epad-plus-plus/issues/17915</div><div><br /></div><div>A potential problem =
with this addition is that it may make bugs less visible by continuing to r=
un with erroneous data. The above Notepad++ issue might not have been treat=
ed as seriously if there hadn't been a hang. Overall, I think the balance i=
s positive here.</div><div><br /></div><div>Neil</div>

<p></p>

-- <br />
You received this message because you are subscribed to the Google Groups &=
quot;scintilla-interest&quot; group.<br />
To unsubscribe from this group and stop receiving emails from it, send an e=
mail to <a href=3D"mailto:[email protected]">=
[email protected]</a>.<br />
To view this discussion visit <a href=3D"https://groups.google.com/d/msgid/=
scintilla-interest/dcb4ce29-39ef-4941-8120-7a08f2518583n%40googlegroups.com=
?utm_medium=3Demail&utm_source=3Dfooter">https://groups.google.com/d/msgid/=
scintilla-interest/dcb4ce29-39ef-4941-8120-7a08f2518583n%40googlegroups.com=
</a>.<br />

------=_Part_138111_1673605737.1776909214737--

------=_Part_138110_1814789555.1776909214737--