Strings

November 05, 2025

AngelScript Strings

Basic String Methods

uint length // Use without "()"

Returns the length of the string.

void resize(uint)

Sets the length of the string.

bool isEmpty() const

Returns true if the string is empty (length is zero).

string substr(uint start = 0, int count = -1) const

Returns a string with the content starting at start and the number of bytes given by count. The default arguments will return the whole string as the new string.

void insert(uint pos, const string &in other)

Inserts another string other at position pos in the original string.

void erase(uint pos, int count = -1)

Erases a range of characters from the string, starting at position pos and counting count characters.

pos = s.findFirst("letimix"); // find substring
log("pos: "+pos); // pos: 7
pos = s.findFirst("e");
log("pos: "+pos); // pos: 3
pos = s.findFirst("e", pos+1); // find next "e"
log("pos: "+pos); // pos: 8
pos = s.findLast("e");
log("pos: "+pos); // pos: 20
pos = s.findLast("e", pos-1); // find previous "e"
log("pos: "+pos); // pos: 8
pos = s.findLast("abc"); // not in the string
log("pos: "+pos); // pos: -1
pos = s.findFirstOf("slD"); // find any of chars
log("pos: "+pos); // pos: 2 ('s' in Users)
pos = s.findFirstOf("slD", pos+1);
log("pos: "+pos); // pos: 5 (next 's' in Users)
pos = s.findLastOf("slD");
log("pos: "+pos); // pos: 23 ('s' in Documents)
pos = s.findLastOf("slD", pos-1);
log("pos: "+pos); // pos: 15 ('D' in Documents)
pos = s.findFirstNotOf("/");
log("pos: "+pos); // pos: 1 ('U' in Users)
pos = s.findFirstNotOf("/", pos+1);
log("pos: "+pos); // pos: 2 ('s' in Users)
pos = s.findLastNotOf("/");
log("pos: "+pos); // pos: 23 ('s' in Documents)
pos = s.findLastNotOf("/", pos-1); // find any of chars
log("pos: "+pos); // pos: 22 ('t' in Documents)

Search Methods

int findFirst(const string &in str, uint start = 0) const

Find the first occurrence of the value str in the string, starting at start. If no occurrence is found a negative value will be returned.

int findLast(const string &in str, int start = -1) const

Find the last occurrence of the value str in the string. If start is informed the search will begin at that position, i.e. any potential occurrence after that position will not be searched. If no occurrence is found a negative value will be returned.

int findFirstOf(const string &in chars, int start = 0) const

Finds the first character in the string that matches one of the characters in chars, starting at start. If no occurrence is found a negative value will be returned.

int findFirstNotOf(const string &in chars, int start = 0) const

Finds the first character that doesn't match any of those in chars.

int findLastOf(const string &in chars, int start = -1) const

Same as findFirstOf but starts the search from the end of the string.

int findLastNotOf(const string &in chars, int start = -1) const

Same as findFirstNotOf but starts the search from the end of the string.

string s = "$_USER_DOCUMENTS_PATH_$";
log(s); // /Users/letimix/Documents
int pos;
pos = s.findFirst("letimix");
log("pos: "+pos); // pos: 7
pos = s.findFirst("e");
log("pos: "+pos); // pos: 3
pos = s.findFirst("e", pos+1); // find next "e"
log("pos: "+pos); // pos: 8
pos = s.findLast("e");
log("pos: "+pos); // pos: 20
pos = s.findLast("e", pos-1); // find previous "e"
log("pos: "+pos); // pos: 8
pos = s.findLast("abc"); // not in the string
log("pos: "+pos); // pos: -1
pos = s.findFirstOf("slD"); // find any of chars
log("pos: "+pos); // pos: 2 ('s' in Users)
pos = s.findFirstOf("slD", pos+1);
log("pos: "+pos); // pos: 5 (next 's' in Users)
pos = s.findLastOf("slD");
log("pos: "+pos); // pos: 23 ('s' in Documents)
pos = s.findLastOf("slD", pos-1);
log("pos: "+pos); // pos: 15 ('D' in Documents)
pos = s.findFirstOf("slD"); // find any of chars
log("pos: "+pos); // pos: 2 ('s' in Users)
pos = s.findFirstNotOf("/");
log("pos: "+pos); // pos: 1 ('U' in Users)
pos = s.findFirstNotOf("/", pos+1);
log("pos: "+pos); // pos: 2 ('s' in Users)
pos = s.findLastNotOf("/");
log("pos: "+pos); // pos: 23 ('s' in Documents)
pos = s.findLastNotOf("/", pos-1); // find any of chars
log("pos: "+pos); // pos: 22 ('t' in Documents)

Split and join

array<string>@ split(const string &in delimiter) const

Splits the string in smaller strings where the delimiter is found.

string join(const array<string> &in arr, const string &in delimiter)

Concatenates the strings in the array into a large string, separated by the delimiter.

string s = "$_USER_DOCUMENTS_PATH_$";
log(s); // /Users/letimix/Documents
array<string> ar = s.split("/");
log("array size: "+ar.length); // 4 (first empty before first /)
for(uint i=0;i<ar.length;i++) {
log(ar[i]); // outputs [empty], Users, letimix, Documents
}
ar.insertLast("Blue Cat Audio"); // add pieces to array
ar.insertLast("Blue Cat's Plug'n Script");
s = join(ar, "/"); // join array back to string
log(s); // /Users/letimix/Documents/Blue Cat Audio/Blue Cat's Plug'n Script

Parsing Functions

int64 parseInt(const string &in str, uint base = 10, uint &out byteCount = 0)

Parses the string for an integer value. The base can be 10 or 16 to support decimal numbers or hexadecimal numbers. If byteCount is provided it will be set to the number of bytes that were considered as part of the integer value.

uint64 parseUInt(const string &in str, uint base = 10, uint &out byteCount = 0)

Same as parseInt but for unsigned integers.

double parseFloat(const string &in, uint &out byteCount = 0)

Parses the string for a floating point value. If byteCount is provided it will be set to the number of bytes that were considered as part of the value.

string s;
s = "123";
int i;
log("--parseInt--");
i = parseInt(s);
log("i: "+i); // i: 123
uint len;
s = "-123.44 miles";
i = parseInt(s, 10, len);
log("i: "+i + " len: "+len); // i: -123 len: 4
s = " 123 number";
i = parseInt(s, 10, len); // can starts only with a number or -,+
log("i: "+i + " len: "+len); // i: 0 len: 0
s = "10e2"; // scientific notation works only with parseFloat
i = parseInt(s);
log("i: "+i); // i: 10
s = "FF";
i = parseInt(s, 16); // convert hex value
log("i: "+i); // i: 255
log("--parseUInt--");
uint u;
s = "123";
u = parseUInt(s);
log("u: "+u); // u: 123
s = "-123";
u = parseUInt(s);
log("u: "+u); // u: 0
s = "-123";
u = parseInt(s); // just to test the difference
log("u: "+u); // u: 4294967173
s = "FF";
u = parseUInt(s, 16); // convert hex value
log("u: "+u); // u: 255
s = "FFCCDD";
u = parseUInt(s, 16, len);
log("u: "+u + " len: "+len); // u: 16764125 len: 6
s = "#FFCCDD"; // will fail cause starts with #
u = parseUInt(s, 16, len);
log("u: "+u + " len: "+len); // u: 0 len: 0
log("--parseFloat--");
double f;
s = "123.45678910";
f = parseFloat(s);
log("f: "+formatFloat(f, "", 3, 10)); // f: 123.4567891000
s = "-1e4 number"; // scientific notation works here
f = parseFloat(s, len);
log("f: "+f + " len: "+len); // f: -10000 len: 4

Formatting Functions

string formatInt(int64 val, const string &in options = "", uint width = 0)
// Blue Cat Audio alternative for DSP thread to convert without memory allocation
void intToString(int64 val, string& s, const string &in options = "", uint width = 0);

Formats an integer value with specified options and width.

string formatUInt(uint64 val, const string &in options = "", uint width = 0)
// Blue Cat Audio alternative for DSP thread to convert without memory allocation
void uIntToString(uint64 val, string& s, const string &in options = "", uint width = 0);

Formats an unsigned integer value with specified options and width.

string formatFloat(double val, const string &in options = "", uint width = 0, uint precision = 0)
// Blue Cat Audio alternative for DSP thread to convert without memory allocation
void floatToString(double val, string& s, const string &in options = "", uint width = 0, uint precision = 0);

Formats a floating-point value with specified options, width, and precision.

Format Options

Character	Description
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 (not valid for formatFloat)
H	hexadecimal integer capital letters (not valid for formatFloat)
e	exponent character with small e (only valid for formatFloat)
E	exponent character with capital E (only valid for formatFloat)

Examples:

string s;
log("--formatInt and intToString--");
s = formatInt(-1000);
log(s); // "-1000"
s = formatInt(1000, "", 10);
log(s); // " 1000" // adds spaces
s = formatInt(1000, "+l", 10);
log(s); // "+1000 " // adds sign and spaces, aligns left
s = formatInt(1000, " l", 10);
log(s); // " 1000 " // same, but adds space instead of +
s = formatInt(255, "h");
log(s); // "ff"
s = formatInt(255, "0H", 6);
log(s); // "0000FF"
intToString(255, s, "0H", 4); // avoids memory allocation
log(s); // "00FF"
log("--formatUInt and uIntToString--");
s = formatUInt(30, "0", 4);
log(s); // "0030"
s = formatUInt(15, "0H", 2); // format two-digit hex
log(s); // "0F"
uIntToString(239, s, "0H", 2); // avoids memory allocation
log(s); // "EF"
log("--formatFloat and floatToString--");
s = formatFloat(123.456789);
log(s); // "123" // cause precision is 0 by default
s = formatFloat(1, "0", 5, 2);
log(s); // "01.00"
s = formatFloat(123.456789, "", 7, 2);
log(s); // " 123.46"
s = formatFloat(123.456789, "+l", 15, 5);
log(s); // "+123.45679 "
s = formatFloat(2345.6789, " ", 15, 5);
log(s); // " 2345.67890"
s = formatFloat(0.05, "e");
log(s); // "5e-02"
floatToString(345.6789, s, "", 3, 2); // avoids memory allocation
log(s); // "345.68"

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.

Note: Unless otherwise stated, all methods and functions work on the individual bytes in the string. They do not attempt to understand encoded characters, e.g. UTF-8 encoded characters that can take up to 4 bytes.

Operators

`=` Assignment

string = string

The assignment operator copies the content of the right hand string into the left hand string.
Assignment of primitive types is allowed, which will do a default transformation of the primitive to a string.

`+`, `+=` Concatenation

string + string
string += string

The concatenation operator appends the content of the right hand string to the end of the left hand string.
Concatenation of primitive types is allowed, which will do a default transformation of the primitive to a string.

`==`, `!=` Equality

string == string
string != string

Compares the content of the two strings.

`<`, `>`, `<=`, `>=` Comparison

string < string
string > string
string <= string
string >= string

Compares the content of the two strings. The comparison is done on the byte values in the strings, which may not correspond to alphabetical comparisons for some languages.

string s1, s2;
s1 = "abc";
s2 = "def";
log(s1 + " > " + s2 + " = " + (s1>s2)); // abc > def = false
log(s1 + " < " + s2 + " = " + (s1<s2)); // abc < def = true
s1 = "abc";
s2 = "ab";
log(s1 + " > " + s2 + " = " + (s1>s2)); // abc > ab = true
log(s1 + " < " + s2 + " = " + (s1<s2)); // abc < ab = false
s1 = "ABC";
s2 = "abc";
log(s1 + " > " + s2 + " = " + (s1>s2)); // ABC > abc = false
log(s1 + " < " + s2 + " = " + (s1<s2)); // ABC < abc = true
s1 = "Abc";
s2 = "aBC";
log(s1 + " > " + s2 + " = " + (s1>s2)); // Abc > aBC = false
log(s1 + " < " + s2 + " = " + (s1<s2)); // Abc < aBC = true
s1 = "Abc";
s2 = "ABC";
log(s1 + " > " + s2 + " = " + (s1>s2)); // Abc > ABC = true
log(s1 + " < " + s2 + " = " + (s1<s2)); // Abc < ABC = false
s1 = "Abc";
s2 = "ABCDE"; // So length is less important than char byte values
log(s1 + " > " + s2 + " = " + (s1>s2)); // Abc > ABCDE = true
log(s1 + " < " + s2 + " = " + (s1<s2)); // Abc < ABCDE = false
s1 = "ABCabc";
s2 = "abc";
log(s1 + " > " + s2 + " = " + (s1>s2)); // ABCabc > abc = false
log(s1 + " < " + s2 + " = " + (s1<s2)); // ABCabc < abc = true
s1 = "abcABC";
s2 = "abc"; // but if starting char values equals, then length is counted
log(s1 + " > " + s2 + " = " + (s1>s2)); // abcABC > abc = true
log(s1 + " < " + s2 + " = " + (s1<s2)); // abcABC < abc = false

`[]` Index Operator

string[index]

The index operator gives access to a single byte in the string.

About strings in AngelScript for Plug'n Script

Strings hold an array of bytes. 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 (with normal "), and the documentation strings, called heredoc strings (with triple """), see below.

Single quotation marks (') in PnS/KUIML are used for single character byte values and not strings. These are useful to access character in a string as a byte value.

uint8 c = 'A'; // can also use uint, int or auto, or even string
log("char: " + c); // char: 65
string s1 = "B";
log("char: " + s1); // char: B
string s2 = 'C';
log("char: " + s2); // char: 67 (s2 is a string holding "67")
string s3 = "ABC";
s3[1] = 65;
s3[2] = 'A';
log("result: " + s3); // result: AAA
log("s3[0] = "+s3[0]); // s3[0] = 65

The normal strings are written between double 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
\xFF	0xFF	FF is a 1 or 2 digit hexadecimal number representing the value wanted
\uFFFF \UFFFFFFFF	0xFFFF 0xFFFFFFFF	FFFF(FFFF) is a hexadecimal number representing the unicode code point

The escape sequences \u and \U will add the specified unicode code point as a UTF-8 encoded sequence. 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.

string s1 = "This is ASCII 65 in hex: \x41, and \"escaped \\ chars\".";
log(s1); // This is ASCII 65 in hex: A, and "escaped \ chars".
s1 = "This has unicode \u0230 \u03E1 \u0498 \U0000266B \U0000222B characters";
log(s1); // This has unicode Ȱ ϡ Ҙ ♫ ∫ characters
string s2 = "This is a way to \0 finish the string.";
log("len: " + s2.length + " | " +s2 + "|"); // len: 37 | This is a way to
log("try 0 char"); // len: 37 | This is a way to try 0 char
for(uint i=0;i<s2.length;i++) { if (s2[i]==0) s2[i]='-'; } // replace 0 with 45
log(s2); // This is a way to - finish the string.

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 s = """
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.
""";
log(s); // (preserved spaces (begin) and newlines (end of lines))

Heredoc strings are very useful in Plug'n Script to parse a VARIABLE containing Windows-style path.

string s1 = "$PLUGIN_DATA_PATH$"; // backslashes are interpreted as escape-chars
log(s1); // C:rogram Filesommon FilesST3C Plug'n Script VST3 data
string s2 = """$PLUGIN_DATA_PATH$"""; // backslashes are preserved
log(s2); // C:\Program Files\Common Files\VST3\BC Plug'n Script VST3 data

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 s2 = "First line.\n" // this is a first line
"Second line.\n"
"Third line." // this is a third one
" And still a third";
log(s2); // (outputs all as expected)

Original documentation

https://www.angelcode.com/angelscript/sdk/docs/manual/doc_script_stdlib_string.html

Comments

Please, authorize to view and post comments.