#1477 Annotate ScintillaCall with const and structure types

[Zufu Liu]

Currently, void * is used for findtext, formatrange, textrange and their full versions, It can be changed to use TextToFind, RangeToFormat, TextRange and the full versions.

All RangeToFormat, TextRange and full versions pointer parameter can de declared as const.

[Neil Hodgson]

ScintillaCall.h and ScintillaStructures.h are parts of the external interface of Scintilla and should not be modified in ways that are incompatible with projects that use these interfaces. These changes break compilation of SciTE. While SciTE can be easily updated, this indicates that other projects are also likely to break.

TextRange is only const in the shallow sense since the memory pointed to by lpstrText is modified - C++ doesn't have deep const which is sometimes called 'frozen'. I feel GetTextRange(const TextRange *tr) is misleading.

[Zufu Liu]

GetTextRange(const TextRange *tr) means not change member them self, e.g. change lpstrText to a new pointer, which is different from FindTextFull(Scintilla::FindOption searchFlags, TextToFindFull *ft), where chrgText member will be updated.

How about the change without adding const?, e.g.:

@@ -18,10 +18,10 @@
    "cells": "const char *",
    "colour": "Colour",
    "colouralpha": "ColourAlpha",
-   "findtext": "void *",
-   "findtextfull": "void *",
-   "formatrange": "void *",
-   "formatrangefull": "void *",
+   "findtext": "TextToFind *",
+   "findtextfull": "TextToFindFull *",
+   "formatrange": "RangeToFormat *",
+   "formatrangefull": "RangeToFormatFull *",
    "int": "int",
    "keymod": "int",
    "line": "Line",
@@ -29,8 +29,8 @@
    "position": "Position",
    "string": "const char *",
    "stringresult": "char *",
-   "textrange": "void *",
-   "textrangefull": "void *",
+   "textrange": "TextRange *",
+   "textrangefull": "TextRangeFull *",
 }

 basicTypes = [

Which will improve readability the of code (they are available like other types in Scintilla:: namespace).

[Neil Hodgson]

The non-"Full" types should be discouraged instead of being made more prominent. They will be deprecated later.

[Zufu Liu]

Then, these non-full version methods can be marked as[[deprecated]].

[Zufu Liu]

OK, only with full version, non-const structures.

[Neil Hodgson]

From rhkramer, trying to reply on scintilla-tracker but its not hooked up to work.

OK, only with full version, non-const structures.

From the peanut gallery, can someonw explain (or point to a good online
explanation or some good search terms) what is meant by a full version in this
context?

The *Full structs (like TextRangeFull) and APIs like SCI_GETTEXTRANGEFULL are compatible with documents larger than 2GB. Due to using 32-bit types that were compatible with the Win32 edit control, the old interfaces like TextRange and SCI_GETTEXTRANGE fail on these huge documents.

[Neil Hodgson]

Committed change as [4d34a3] only for *Full structures. Added forward declarations in ScintillaCall.h to maintain compatibility for most projects.