String Functions

AeroScript data types include UTF-8 capable strings. You can use all string functions on strings that are single-byte or multi-byte characters. The controller also has predefined global string variables that you can use to pass strings between tasks. For more information, see Global Variables.

Basic String Operations

String Literals

Declare string literals with double quotes by using the escape sequence, \". For example:

var $return as integer
$return = StringLength("Single quote: ‘  backslash: \\")

The table that follows includes a full list of available escape sequences.

Table: AeroScript Escape Sequences

Escape Sequence	Character*
\a	Alarm
\b	Backspace
\f	Form feed
\n	Newline
\r	Carriage return
\t	Horizontal tab
\v	Vertical tab
\\	Backslash (\)
\”	Double quote (")
\nnn	ASCII character with given octal value (n=an octal digit 1-7)
\xhh	ASCII character with given hex value (hh=one or two hex digits 1-F)
\Uhhhh	Unicode 16-bit code point (h=a hex digit 1-F)
\Uhhhhhhhh	Unicode 32-bit code point (h=a hex digit 1-F)
*Use of the null terminator (\0) in a string will result in a compiler error.

Declare a String

Specify the capacity of a string variable in parentheses. If you do not include a string capacity, the string capacity defaults to 256. The maximum string capacity in AeroScript is 2,500 UTF-8 characters even if individual characters include multi-byte code points.

The StringStackSize Parameter limits the number of strings a program can use. When you declare a string outside of a program or function block, it is not limited by the StringStackSize parameter.

Strings can be initialized on the same line they are declared. See the example that follows.

var $myStr as string(32) = "Hello World! ☺"

String Concatenation

Concatenate strings with the “+” operator. The StringStackSize parameter also limits string concatenation.

var $myStr1 as string(32) = "Time: "
var $myStr2 as string(32)
$myStr2 = $myStr1 + "12:00pm"

String Functions

String Programming Functions

Because UTF-8 can show the same string in different ways, the StringLength() and StringReplace() functions can behave differently based on how the input string is represented. The StringNormalize() function forces a string to a standard representation.

Always use the StringNormalize() function to compare user text input to a known string. All indices in the functions that follow are in terms of UTF-8 characters.

The functions that follow include the string programming functions.

String Utility Functions

Use the function that follows to determine if a string value represents a valid UTF-8 string. You must make sure a string is valid before you use it if you read the string from a file or from a socket. For more information, refer to File and Directory Functions and Socket Functions.

String Conversion Functions

Conversion functions cause task errors if an input cannot be converted. You can use the StringIsAlphabetic(), StringIsInteger(), StringIsReal(), and StringIsWhitespace() functions to determine if you can convert a string.

The IntegerToString() function lets you use different number bases when converting integer values to strings. Use the NumberBase enum with the IntegerToString() function to change the number base of the integer in the string. If the number base is hexadecimal, alphabetical characters from the conversion will be lowercase. If you want the hexadecimal string output to have capital letters, use the StringToUpperCase() function.

// Outputs "BEEF"
AppMessageDisplay(StringToUpperCase(IntegerToString(0xbeef,
NumberBase.Hexadecimal)))

The IntegerToString() function also lets you set the minimum width of the integer string. If the result is a string that is shorter than the specified width, the string is filled with zeros until it gets to the minimum width. If the string is longer than the minimum width, the string is not filled with zeros. If the integer is negative, the string is filled with zeros. If the number base of the integer string is decimal and the integer is negative, a minus sign will be added first and then the zeros will be added to get to the minimum width.

The examples that follow show how to use the IntegerToString() function with different number bases and minimum widths.

Program Example

var $myInteger as integer = 10

// IntegerToString() outputs "10".
AppMessageDisplay(IntegerToString($myInteger))

// IntegerToString() outputs "1010".
AppMessageDisplay("0b" + IntegerToString($myInteger, NumberBase.Binary))

// IntegerToString() outputs "12".
AppMessageDisplay("0" + IntegerToString($myInteger, NumberBase.Octal))

// IntegerToString() outputs "a".
AppMessageDisplay("0x" + IntegerToString($myInteger, NumberBase.Hexadecimal))

// IntegerToString() outputs "0000000a".
AppMessageDisplay("0x" + IntegerToString($myInteger, NumberBase.Hexadecimal, 8))

// IntegerToString() outputs "-010".
AppMessageDisplay(IntegerToString(-$myInteger, NumberBase.Decimal, 4))

The RealToString() function lets you use decimal and scientific formats to convert real values to strings. Use the RealDisplayFormat enum with the RealToString() function to show how a real should be formatted within the string.

The examples that follow show how to use the RealToString() function with different formatting options.

Example: Decimal Format

// Converts to "10000.123450"
AppMessageDisplay("String 1: " + RealToString(10000.12345, RealDisplayFormat.Decimal))

// Converts to "10000.123"
AppMessageDisplay("String 2: " + RealToString(10000.12345, RealDisplayFormat.Decimal, 3))

// Converts to "  10000.1234"
AppMessageDisplay("String 3: " + RealToString(10000.12345, RealDisplayFormat.Decimal, 4, 12))

Example: Scientific Format

// Converts to "1.000012e+04"
AppMessageDisplay("String 4: " + RealToString(10000.12345, RealDisplayFormat.Scientific))

// Converts to "1.000e+04"
AppMessageDisplay("String 5: " + RealToString(10000.12345, RealDisplayFormat.Scientific, 3))

// Converts to "1.0000123e+04"
AppMessageDisplay("String 6: " + RealToString(10000.12345, RealDisplayFormat.Scientific, 7))

Example: Compact Format

// Converts to "10000.1"
AppMessageDisplay("String 7: " + RealToString(10000.12345, RealDisplayFormat.Compact))

// Converts to "1e+04"
AppMessageDisplay("String 8: " + RealToString(10000.12345, RealDisplayFormat.Compact, 3))

// Converts to "10000.123"
AppMessageDisplay("String 9: " + RealToString(10000.12345, RealDisplayFormat.Compact, 8))

String Functions

Basic String Operations

String Literals

Declare a String

String Concatenation

String Functions

String Programming Functions

String Utility Functions

String Conversion Functions

String Formatting Functions