| AngelScript

Strings

Note
  Strings are only available in the scripts if the application registers the support for them. The syntax for using strings may differ for the application you're working with so consult the application's manual for more details.

Strings hold an array of bytes or 16bit words depending on the application settings. Normally they are used to store text but can really store any kind of binary data.

There are two types of string constants supported in the AngelScript language, the normal quoted string, and the documentation strings, called heredoc strings.

The normal strings are written between double quotation marks (`"`) or single quotation marks (`'`). Inside the constant strings some escape sequences can be used to write exact byte values that might not be possible to write in your normal editor.

sequence | value | description
`\0` | 0 | null character
`\\` | 92 | back-slash
`\'` | 39 | single quotation mark (apostrophe)
`\"` | 34 | double quotation mark
`\n` | 10 | new line feed
`\r` | 13 | carriage return
`\t` | 9 | tab character
`\xFFFF` | 0xFFFF | FFFF should be exchanged for a 1 to 4 digit hexadecimal number representing the value wanted. If the application uses 8bit strings then only values up to 255 is accepted.
`\uFFFF` | 0xFFFF | FFFF should be exchanged for the hexadecimal number representing the unicode code point
`\UFFFFFFFF` | 0xFFFFFFFF | FFFFFFFF should be exchanged for the hexadecimal number representing the unicode code point

      string str1 = "This is a string with \"escape sequences" .";
      string str2 = 'If single quotes are used then double quotes can be included without "escape sequences".';

The heredoc strings are designed for inclusion of large portions of text without processing of escape sequences. A heredoc string is surrounded by triple double-quotation marks (`"""`), and can span multiple lines of code. If the characters following the start of the string until the first linebreak only contains white space, it is automatically removed by the compiler. Likewise if the characters following the last line break until the end of the string only contains white space this is also removed.

      string str = """
      This is some text without "escape sequences". This is some text.
      This is some text. This is some text. This is some text. This is
      some text. This is some text. This is some text. This is some
      text. This is some text. This is some text. This is some text.
      This is some text.
      """;

If more than one string constants are written in sequence with only whitespace or comments between them the compiler will concatenate them into one constant.

      string str = "First line.\n"
                   "Second line.\n"
                   "Third line.\n";

The escape sequences \u and \U will add the specified unicode code point as a UTF-8 or UTF-16 encoded sequence depending on the application settings. Only valid unicode 5.1 code points are accepted, i.e. code points between U+D800 and U+DFFF (reserved for surrogate pairs) or above U+10FFFF are not accepted.

# Supporting string object and functions

The string object supports a number of operators, and has several class methods and supporting global functions to facilitate the manipulation of strings.

## Operators

- = assignment
- +, += concatenation
- ==, != equality
- <, >, <=, >= comparison
- [] index operator

Concatenation or assignment with primitives is allowed, and will then do a default transformation of the primitive to a string.

## Methods

- uint length() const
- void resize(uint)
- bool isEmpty() const
- string substr(uint start = 0, int count = -1) const
- int findFirst(const string &in str, uint start = 0) const
- int findLast(const string &in str, int start = -1) const
- array<string>@ split(const string &in delimiter) const

## Functions

- string join(const array<string> &in arr, const string &in delimiter)
- int64 parseInt(const string &in, uint base = 10, uint &out byteCount = 0)
- double parseFloat(const string &in, uint &out byteCount = 0)
- string formatInt(int64 val, const string &in options = '', uint width = 0)
- string formatUInt(uint64 val, const string &in options = '', uint width = 0)
- string formatFloat(double val, const string &in options = '', uint width = 0, uint precision = 0)

The format functions takes a string that defines how the number should be formatted. The string is a combination of the following characters:

- l = left justify
- 0 = pad with zeroes
- + = always include the sign, even if positive
- space = add a space in case of positive number
- h = hexadecimal integer small letters
- H = hexadecimal integer capital letters
- e = exponent character with small e
- E = exponent character with capital E

Examples:

      // Left justify number in string with 10 characters
      string justified = formatInt(number, 'l', 10);

      // Create hexadecimal representation with capital letters, right justified
      string hex = formatInt(number, 'H', 10);

      // Right justified, padded with zeroes and two digits after decimal separator
      string num = formatFloat(number, '0', 8, 2);