String type

The string type is used to hold a finite sequence of characters.

String declaration

The keyword indicating a string variable is str.

According to the Best Practice Handbook, strings used for user interface purposes should be surrounded with double-quotes ("), and should use a label code where possible. Those for internal/system purposes should use single-quotes (').

<xpp> str someSystemStringVariable = 'Initial value'; </xpp>

strFmt

The strFmt() method should be used to produce strings for user interface use, where the contents of a variable need to be inserted into a constant string. The string constant should contain placeholders %1, %2, etc. which will be replaced with subsequent parameters to the strFmt call.

The most common use of this is for formatting output using label files. For example, the system label @SYS17145 contains the text Journal number '%1' does not exist.

We can use this to produce an informative error message for the user. If we assume that we have a variable named journalId which contains '000984', then the following:

<xpp> s = strFmt("@SYS17145", journalId); </xpp>

will populate s with Journal number '000984' does not exist.

Escape sequences

X++, as with many languages, allows the use of escape sequences inside a string to represent special characters. These sequences are actually two characters (a backslash "\" followed by another character), but are treated as a single character.

These codes are identical to those available in C, C# and similar languages, such as "\r" for a carriage return and "\n" for a newline character.

To include the contents of an escape sequence as normal characters, then you need to "escape" the special code by prefixing another backslash. Therefore to include "\r" as literal strings, rather than a carriage return, you would input "\\r" into your string variable.

Verbatim string syntax

It is also possible to use a special Verbatim String syntax to create multi-line strings, and strings where escape sequences will be ignored. To mark a string as verbatim, simply include a @ character before the opening quote. See below for an example of this technique.

Various examples

<xpp> str s;

s = 'string'; // Normal string for system purposes (note single quotes)

s = "@SYS2120"; // UI String - using a label code (note double quotes)

s = 'string\r'; // String with a terminating carriage-return, due to the "escaping" extra backslash

s = 'string\\r'; // String ending with the literal \r

s = @'string

     on
     multiple
     lines
     \r'; // Multi-line string ending with the literal \r.  
          // Note that with the @ prefix, escape characters are ignored and everything is treated as a literal

</xpp>