Specify which APIs append a NUL to results.

2 files changed, 36 insertions, 20 deletions

diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html
index b75d3c399..da63297bf 100644
--- a/doc/ScintillaDoc.html
+++ b/doc/ScintillaDoc.html
@@ -169,7 +169,9 @@
           <td>Arguments point at text buffers that Scintilla will fill with text. In some cases,
           another argument will tell Scintilla the buffer size. In others, you must make sure that
           the buffer is big enough to hold the requested text. If a NULL pointer (0) is passed
-          then, for SCI_* calls, the length that should be allocated is returned.</td>
+          then, for SCI_* calls, the length that should be allocated, not including any terminating
+          NUL, is returned. Some calls (marked "NUL-terminated") add a NUL character to the result but other calls do
+          not: to generically handle both types, allocate one more byte than indicated and set it to NUL.</td>
         </tr>
 
         <tr>
@@ -417,7 +419,7 @@
      <a class="message" href="#SCI_SETLENGTHFORENCODE">SCI_SETLENGTHFORENCODE(int bytes)</a><br />
     </code>
 
-    <p><b id="SCI_GETTEXT">SCI_GETTEXT(int length, char *text)</b><br />
+    <p><b id="SCI_GETTEXT">SCI_GETTEXT(int length, char *text NUL-terminated)</b><br />
      This returns <code>length</code>-1 characters of text from the start of the document plus one
     terminating 0 character. To collect all the text in a document, use <code>SCI_GETLENGTH</code>
     to get the number of characters in the document (<code>nLen</code>), allocate a character
@@ -700,7 +702,7 @@ struct Sci_TextRange {
            After replacement, the target range refers to the replacement text.
            The return value is the length of the replacement string.</p>
 
-    <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</b><br />
+    <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue NUL-terminated)</b><br />
      Discover what text was matched by tagged expressions in a regular expression search.
      This is useful if the application wants to interpret the replacement string itself.</p>
 
@@ -1331,7 +1333,7 @@ struct Sci_TextToFind {
     href="#SCI_GETLINEENDPOSITION"><code>SCI_GETLINEENDPOSITION(line)</code></a> - <a class="message"
     href="#SCI_POSITIONFROMLINE"><code>SCI_POSITIONFROMLINE(line)</code></a>.</p>
 
-    <p><b id="SCI_GETSELTEXT">SCI_GETSELTEXT(&lt;unused&gt;, char *text)</b><br />
+    <p><b id="SCI_GETSELTEXT">SCI_GETSELTEXT(&lt;unused&gt;, char *text NUL-terminated)</b><br />
      This copies the currently selected text and a terminating 0 byte to the <code>text</code>
     buffer. The buffer size should be determined by calling with a NULL pointer for the <code>text</code> argument
     <code>SCI_GETSELTEXT(0,0)</code>.
@@ -1346,7 +1348,7 @@ struct Sci_TextToFind {
     <a class="message" href="#SCI_GETTEXTRANGE">SCI_GETTEXTRANGE</a>
     </code></p>
 
-    <p><b id="SCI_GETCURLINE">SCI_GETCURLINE(int textLen, char *text)</b><br />
+    <p><b id="SCI_GETCURLINE">SCI_GETCURLINE(int textLen, char *text NUL-terminated)</b><br />
      This retrieves the text of the line containing the caret and returns the position within the
     line of the caret. Pass in <code>char* text</code> pointing at a buffer large enough to hold
     the text you wish to retrieve and a terminating 0 character.
@@ -2573,7 +2575,7 @@ struct Sci_TextToFind {
      3. Set the style attributes that make your lexical styles different.</p>
 
     <p><b id="SCI_STYLESETFONT">SCI_STYLESETFONT(int styleNumber, const char *fontName)</b><br />
-    <b id="SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName)</b><br />
+    <b id="SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName NUL-terminated)</b><br />
     <b id="SCI_STYLESETSIZE">SCI_STYLESETSIZE(int styleNumber, int sizeInPoints)</b><br />
     <b id="SCI_STYLEGETSIZE">SCI_STYLEGETSIZE(int styleNumber)</b><br />
     <b id="SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)</b><br />
@@ -2878,7 +2880,7 @@ struct Sci_TextToFind {
     </code>
 
     <p><b id="SCI_SETREPRESENTATION">SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)</b><br />
-     <b id="SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation)</b><br />
+     <b id="SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation NUL-terminated)</b><br />
      <b id="SCI_CLEARREPRESENTATION">SCI_CLEARREPRESENTATION(const char *encodedCharacter)</b><br />
     Any character, including those normally displayed  as mnemonics may be represented by a
     string inverted in a rounded rectangle.</p>
@@ -4405,7 +4407,7 @@ struct Sci_TextToFind {
     href="#SCI_AUTOCSETAUTOHIDE"><code>SCI_AUTOCSETAUTOHIDE</code></a>).<br />
     The current selection index can be retrieved with <code>SCI_AUTOCGETCURRENT</code>.</p>
 
-    <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(&lt;unused&gt;, char *text)</b><br />
+    <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(&lt;unused&gt;, char *text NUL-terminated)</b><br />
      This message retrieves the current selected text in the autocompletion list. Normally the
     <a class="message" href="#SCN_AUTOCSELECTION"><code>SCN_AUTOCSELECTION</code></a> notification
     is used instead.</p>
@@ -6102,7 +6104,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     assigns unused lexer numbers to.</p>
 
     <p><b id="SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(&lt;unused&gt;, const char *name)</b><br />
-    <b id="SCI_GETLEXERLANGUAGE">SCI_GETLEXERLANGUAGE(&lt;unused&gt;, char *name)</b><br />
+    <b id="SCI_GETLEXERLANGUAGE">SCI_GETLEXERLANGUAGE(&lt;unused&gt;, char *name NUL-terminated)</b><br />
      <code>SCI_SETLEXERLANGUAGE</code> lets you select a lexer by name, and is the only method if you are using an
     external lexer or if you have written a lexer module for a language of your own and do not wish
     to assign it an explicit lexer number. To select an existing lexer, set <code>name</code> to
@@ -6133,9 +6135,9 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     Indicate that the internal state of a lexer has changed over a range and therefore
     there may be a need to redraw.</p>
 
-    <p><b id="SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(&lt;unused&gt;, char *names)</b><br />
+    <p><b id="SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(&lt;unused&gt;, char *names NUL-terminated)</b><br />
     <b id="SCI_PROPERTYTYPE">SCI_PROPERTYTYPE(const char *name)</b><br />
-    <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</b><br />
+    <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description NUL-terminated)</b><br />
     Information may be retrieved about the properties that can be set for the current lexer.
     This information is only available for newer lexers.
     <code>SCI_PROPERTYNAMES</code> returns a string with all of the valid properties separated by "\n".
@@ -6174,7 +6176,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     Documentation for the property may be located above the call as a multi-line comment starting with
     <br/><code>// property &lt;property-name&gt;</code></p>
 
-    <p><b id="SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value)</b><br />
+    <p><b id="SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value NUL-terminated)</b><br />
     Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
     buffer and return the length (not including the terminating 0).  If not found, copy an empty string
     to the buffer and return 0.</p>
@@ -6226,7 +6228,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     There is nothing to stop you building your own keyword lists into the lexer, but this means
     that the lexer must be rebuilt if more keywords are added.</p>
 
-    <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(&lt;unused&gt;, char *descriptions)</b><br />
+    <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(&lt;unused&gt;, char *descriptions NUL-terminated)</b><br />
     A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p>
 
     <h3 id="Substyles">Substyles</h3>
@@ -6237,7 +6239,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     each purpose.
     Lexers have to explicitly support this feature by implementing the methods in <code>ILexerWithSubStyles</code>.</p>
 
-    <p><b id="SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(&lt;unused&gt;, char *styles)</b><br />
+    <p><b id="SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(&lt;unused&gt;, char *styles NUL-terminated)</b><br />
      Fill <code>styles</code> with a byte for each style that can be split into substyles.</p>
 
     <p><b id="SCI_DISTANCETOSECONDARYSTYLES">SCI_DISTANCETOSECONDARYSTYLES</b><br />
diff --git a/include/Scintilla.iface b/include/Scintilla.iface
index e9db97984..6432d37aa 100644
--- a/include/Scintilla.iface
+++ b/include/Scintilla.iface
@@ -72,11 +72,11 @@
 
 ## Line numbers and positions start at 0.
 ## String arguments may contain NUL ('\0') characters where the calls provide a length
-## argument and retrieve NUL characters. All retrieved strings except for those retrieved
-## by GetLine also have a NUL appended but client code should calculate the size that
-## will be returned rather than relying upon the NUL whenever possible. Allow for the
-## extra NUL character when allocating buffers. The size to allocate for a stringresult
-## can be determined by calling with a NULL (0) pointer.
+## argument and retrieve NUL characters. APIs marked as NUL-terminated also have a
+## NUL appended but client code should calculate the size that will be returned rather
+## than relying upon the NUL whenever possible. Allow for the extra NUL character when
+## allocating buffers. The size to allocate for a stringresult (not including NUL) can be
+## determined by calling with a NULL (0) pointer.
 
 cat Basics
 
@@ -186,6 +186,7 @@ set void SetAnchor=2026(position posAnchor,)
 
 # Retrieve the text of the line containing the caret.
 # Returns the index of the caret on the line.
+# Result is NUL-terminated.
 fun int GetCurLine=2027(int length, stringresult text)
 
 # Retrieve the position of the last correctly styled character.
@@ -479,6 +480,7 @@ get int StyleGetSize=2485(int style,)
 
 # Get the font of a style.
 # Returns the length of the fontName
+# Result is NUL-terminated.
 get int StyleGetFont=2486(int style, stringresult fontName)
 
 # Get is a style to have its end of line filled or not.
@@ -578,7 +580,7 @@ set void SetCaretPeriod=2076(int periodMilliseconds,)
 set void SetWordChars=2077(, string characters)
 
 # Get the set of characters making up words for when moving or selecting by word.
-# Retuns the number of characters
+# Returns the number of characters
 get int GetWordChars=2646(, stringresult characters)
 
 # Start a sequence of actions that is undone and redone as a unit.
@@ -951,6 +953,7 @@ fun void SetSel=2160(position start, position end)
 
 # Retrieve the selected text.
 # Return the length of the text.
+# Result is NUL-terminated.
 fun int GetSelText=2161(, stringresult text)
 
 # Retrieve a range of text.
@@ -1021,6 +1024,7 @@ fun void SetText=2181(, string text)
 
 # Retrieve all the text in the document.
 # Returns number of characters retrieved.
+# Result is NUL-terminated.
 fun int GetText=2182(int length, stringresult text)
 
 # Retrieve the number of characters in the document.
@@ -1396,6 +1400,7 @@ set void SetMultiPaste=2614(int multiPaste,)
 get int GetMultiPaste=2615(,)
 
 # Retrieve the value of a tag from a regular expression search.
+# Result is NUL-terminated.
 get int GetTag=2616(int tagNumber, stringresult tagValue)
 
 # Make the target range start and end be the same as the selection range start and end.
@@ -1943,6 +1948,7 @@ get int AutoCGetCurrent=2445(,)
 
 # Get currently selected item text in the auto-completion list
 # Returns the length of the item text
+# Result is NUL-terminated.
 get int AutoCGetCurrentText=2610(, stringresult s)
 
 enu CaseInsensitiveBehaviour=SC_CASEINSENSITIVEBEHAVIOUR_
@@ -2446,6 +2452,7 @@ get int GetLineEndTypesActive=2658(,)
 set void SetRepresentation=2665(string encodedCharacter, string representation)
 
 # Set the way a character is drawn.
+# Result is NUL-terminated.
 get int GetRepresentation=2666(string encodedCharacter, stringresult representation)
 
 # Remove a character representation.
@@ -2482,10 +2489,12 @@ set void SetLexerLanguage=4006(, string language)
 fun void LoadLexerLibrary=4007(, string path)
 
 # Retrieve a "property" value previously set with SetProperty.
+# Result is NUL-terminated.
 get int GetProperty=4008(string key, stringresult buf)
 
 # Retrieve a "property" value previously set with SetProperty,
 # with "$()" variable replacement on returned buffer.
+# Result is NUL-terminated.
 get int GetPropertyExpanded=4009(string key, stringresult buf)
 
 # Retrieve a "property" value previously set with SetProperty,
@@ -2497,12 +2506,14 @@ get int GetStyleBitsNeeded=4011(,)
 
 # Retrieve the name of the lexer.
 # Return the length of the text.
+# Result is NUL-terminated.
 get int GetLexerLanguage=4012(, stringresult text)
 
 # For private communication between an application and a known lexer.
 fun int PrivateLexerCall=4013(int operation, int pointer)
 
 # Retrieve a '\n' separated list of properties understood by the current lexer.
+# Result is NUL-terminated.
 fun int PropertyNames=4014(, stringresult names)
 
 enu TypeProperty=SC_TYPE_
@@ -2514,9 +2525,11 @@ val SC_TYPE_STRING=2
 fun int PropertyType=4015(string name,)
 
 # Describe a property.
+# Result is NUL-terminated.
 fun int DescribeProperty=4016(string name, stringresult description)
 
 # Retrieve a '\n' separated list of descriptions of the keyword sets understood by the current lexer.
+# Result is NUL-terminated.
 fun int DescribeKeyWordSets=4017(, stringresult descriptions)
 
 # Bit set of LineEndType enumertion for which line ends beyond the standard
@@ -2549,6 +2562,7 @@ set void SetIdentifiers=4024(int style, string identifiers)
 get int DistanceToSecondaryStyles=4025(,)
 
 # Get the set of base styles that can be extended with sub styles
+# Result is NUL-terminated.
 get int GetSubStyleBases=4026(, stringresult styles)
 
 # Notifications