From 7c87c9ff57fd657af90aeaedfcaaf607a866ee4b Mon Sep 17 00:00:00 2001 From: Neil Date: Thu, 26 Mar 2015 11:09:46 +1100 Subject: Specify which APIs append a NUL to results. --- doc/ScintillaDoc.html | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'doc/ScintillaDoc.html') 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 @@ 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. + 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. @@ -417,7 +419,7 @@ SCI_SETLENGTHFORENCODE(int bytes)
-

SCI_GETTEXT(int length, char *text)
+

SCI_GETTEXT(int length, char *text NUL-terminated)
This returns length-1 characters of text from the start of the document plus one terminating 0 character. To collect all the text in a document, use SCI_GETLENGTH to get the number of characters in the document (nLen), 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.

-

SCI_GETTAG(int tagNumber, char *tagValue)
+

SCI_GETTAG(int tagNumber, char *tagValue NUL-terminated)
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.

@@ -1331,7 +1333,7 @@ struct Sci_TextToFind { href="#SCI_GETLINEENDPOSITION">SCI_GETLINEENDPOSITION(line) - SCI_POSITIONFROMLINE(line).

-

SCI_GETSELTEXT(<unused>, char *text)
+

SCI_GETSELTEXT(<unused>, char *text NUL-terminated)
This copies the currently selected text and a terminating 0 byte to the text buffer. The buffer size should be determined by calling with a NULL pointer for the text argument SCI_GETSELTEXT(0,0). @@ -1346,7 +1348,7 @@ struct Sci_TextToFind { SCI_GETTEXTRANGE

-

SCI_GETCURLINE(int textLen, char *text)
+

SCI_GETCURLINE(int textLen, char *text NUL-terminated)
This retrieves the text of the line containing the caret and returns the position within the line of the caret. Pass in char* text 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.

SCI_STYLESETFONT(int styleNumber, const char *fontName)
- SCI_STYLEGETFONT(int styleNumber, char *fontName)
+ SCI_STYLEGETFONT(int styleNumber, char *fontName NUL-terminated)
SCI_STYLESETSIZE(int styleNumber, int sizeInPoints)
SCI_STYLEGETSIZE(int styleNumber)
SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)
@@ -2878,7 +2880,7 @@ struct Sci_TextToFind {

SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)
- SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation)
+ SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation NUL-terminated)
SCI_CLEARREPRESENTATION(const char *encodedCharacter)
Any character, including those normally displayed as mnemonics may be represented by a string inverted in a rounded rectangle.

@@ -4405,7 +4407,7 @@ struct Sci_TextToFind { href="#SCI_AUTOCSETAUTOHIDE">SCI_AUTOCSETAUTOHIDE).
The current selection index can be retrieved with SCI_AUTOCGETCURRENT.

-

SCI_AUTOCGETCURRENTTEXT(<unused>, char *text)
+

SCI_AUTOCGETCURRENTTEXT(<unused>, char *text NUL-terminated)
This message retrieves the current selected text in the autocompletion list. Normally the SCN_AUTOCSELECTION notification is used instead.

@@ -6102,7 +6104,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ assigns unused lexer numbers to.

SCI_SETLEXERLANGUAGE(<unused>, const char *name)
- SCI_GETLEXERLANGUAGE(<unused>, char *name)
+ SCI_GETLEXERLANGUAGE(<unused>, char *name NUL-terminated)
SCI_SETLEXERLANGUAGE 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 name 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.

-

SCI_PROPERTYNAMES(<unused>, char *names)
+

SCI_PROPERTYNAMES(<unused>, char *names NUL-terminated)
SCI_PROPERTYTYPE(const char *name)
- SCI_DESCRIBEPROPERTY(const char *name, char *description)
+ SCI_DESCRIBEPROPERTY(const char *name, char *description NUL-terminated)
Information may be retrieved about the properties that can be set for the current lexer. This information is only available for newer lexers. SCI_PROPERTYNAMES 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
// property <property-name>

-

SCI_GETPROPERTY(const char *key, char *value)
+

SCI_GETPROPERTY(const char *key, char *value NUL-terminated)
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.

@@ -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.

-

SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)
+

SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions NUL-terminated)
A description of all of the keyword sets separated by "\n" is returned by SCI_DESCRIBEKEYWORDSETS.

Substyles

@@ -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 ILexerWithSubStyles.

-

SCI_GETSUBSTYLEBASES(<unused>, char *styles)
+

SCI_GETSUBSTYLEBASES(<unused>, char *styles NUL-terminated)
Fill styles with a byte for each style that can be split into substyles.

SCI_DISTANCETOSECONDARYSTYLES
-- cgit v1.2.3