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.

function StringLength($string as string) as integer

Returns the length of the specified string.

Arguments

$string A string.

Returns

The length of the string.

function StringCapacity($string as string) as integer

Returns the capacity of the specified string.

Arguments

$string A string.

Returns

The capacity of the string.

function StringInsert($string as string, $index as integer, $substring as string) as string

Inserts a string within a specified string.

Arguments

$string The string with which to insert the substring.

$index The index of the string to insert the substring.

$substring The substring to insert within the string.

Returns

The specified string with the specified substring inserted at the specified index.

function StringReplace($string as string, $substring as string, $replacement as string) as string

Replaces the portion of a specified string containing the specified substring with the specified replacement string.

Arguments

$string The string with which to replace a substring.

$substring The substring to replace within the string.

$replacement The string with which to replace the substring.

Returns

The specified string with the specified substring replaced with the replacement string.

function StringSplit($input as string, $delimiters[] as string, ref $substrings[] as string) as integer

Returns an array of substrings of a specified string that is split by the specified delimiters.

Arguments

$input The string from which to get the substrings.

$delimiters An array of single character delimiters with which to split the specified string.

ref $substrings An array of substrings of the specified string.

Returns

The number of substrings in the $substrings array.

function StringSplit($input as string, $delimiters[] as string, ref $substrings[] as string, $maxSubstrings as integer) as integer

Returns an array of substrings of a specified string that is split by the specified delimiters.

Arguments

$input The string from which to get the substrings.

$delimiters An array of single character delimiters with which to split the specified string.

ref $substrings An array of substrings of the specified string.

$maxSubstrings The maximum number of substrings to get from the specified string.

Returns

The number of substrings in the $substrings array.

function StringSubstring($string as string, $startIndex as integer, $numCharacters as integer) as string

Returns a substring of a specified string that contains up to the given number of characters.

Arguments

$string The string from which to get a substring.

$startIndex The index of the first character of the substring.

$numCharacters The number of characters to include in the substring.

Returns

The substring of the specified string.

function StringFindSubstringIndex($string as string, $substring as string) as integer

Returns the index of a substring within the specified string.

Arguments

$string The string from which to find the substring.

$substring The substring to find within the string.

Returns

The index of the substring if it is found. Otherwise -1.

function StringFindSubstringIndex($string as string, $substring as string, $startIndex as integer) as integer

Returns the index of a substring within the specified string.

Arguments

$string The string from which to find the substring.

$substring The substring to find within the string.

$startIndex The index of the string to start searching for the substring.

Returns

The index of the substring if it is found. Otherwise -1.

function StringCharacterAt($string as string, $index as integer) as string

Returns the character at the specified index from the specified string.

Arguments

$string The string from which to get a character.

$index The index into the string from which to get a character.

Returns

The character at the specified index of the string.

function StringEquals($string1 as string, $string2 as string) as integer

Returns whether the specified strings are equivalent.

Arguments

$string1 The first string to compare.

$string2 The second string to compare.

Returns

1 if the strings are equivalent. 0 otherwise.

function StringNormalize($string as string) as string

Returns a copy of the specified string in a normalized form.

Arguments

$string The string to normalize.

Returns

The specified string after normalization.

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.

function StringIsValid($string as string) as integer

Returns whether the specified string is valid.

Arguments

$string The string to validate.

Returns

Returns 1 if the string is valid, 0 otherwise.

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 functions that follow include the string conversion functions.

function AxisToString($value as axis) as string

Returns the string representation of the specified axis value.

Arguments

$value The axis value to convert to a string.

Returns

The string representation of the specified axis.

function IntegerToString($value as integer) as string

Returns the string representation of the specified integer value.

Arguments

$value The integer value to convert to a string.

Returns

The string representation of the specified integer.

function IntegerToString($value as integer, $base as NumberBase) as string

Returns the string representation of the specified integer value in the specified base representation.

Arguments

$value The integer value to convert to a string.

$base The number base representation to use.

Returns

The string representation of the specified integer in the specified base representation.

function IntegerToString($value as integer, $base as NumberBase, $width as integer) as string

Returns the string representation of the specified integer value in the specified base representation with a defined width.

Arguments

$value The integer value to convert to a string.

$base The number base representation to use.

$width The minimum width that the string must be. If the string is shorter than the specified width, the value is padded with zeros.

Returns

The string representation of the specified integer value in the specified base representation with the defined width.

function RealToString($value as real) as string

Returns the string representation of the specified real value.

Arguments

$value The real value to convert to a string.

Returns

The string representation of the specified real.

function RealToString($value as real, $format as RealDisplayFormat) as string

Returns the string representation of the specified real value.

Arguments

$value The real value to convert to a string.

$format The display format for the returned real.

Returns

The string representation of the specified real.

function RealToString($value as real, $format as RealDisplayFormat, $precision as integer) as string

Returns the string representation of the specified real value.

Arguments

$value The real value to convert to a string.

$format The display format for the returned string.

$precision The number of digits after the decimal point in the returned string when used with RealDisplayFormat.Decimal or RealDisplayFormat.Scientific. The maximum number of significant digits in the returned string when used with RealDisplayFormat.Compact.

Returns

The string representation of the specified real.

function RealToString($value as real, $format as RealDisplayFormat, $precision as integer, $width as integer) as string

Returns the string representation of the specified real value.

Arguments

$value The real value to convert to a string.

$format The display format for the returned real.

$width The minimum number of characters the returned string will be, includes the decimal point.

Returns

The string representation of the specified real.

function StringToInteger($string as string) as integer

Returns the integer value of the specified string.

Arguments

$string The string from which to get the integer value.

Returns

The integer value of the specified string.

function StringToReal($string as string) as real

Returns the real value of the specified string.

Arguments

$string The string from which to get the real value.

Returns

The real value of the specified 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.

Program Example

// 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 Formatting Functions

The functions that follow are string formatting functions.

function StringToLowerCase($string as string) as string

Returns a copy of the specified string converted to lowercase.

Arguments

$string The string to convert to lowercase.

Returns

The specified string converted to lowercase.

function StringToUpperCase($string as string) as string

Returns a copy of the specified string converted to uppercase.

Arguments

$string The string to convert to uppercase.

Returns

The specified string converted to uppercase.

function StringTrim($string as string) as string

Returns a copy of the specified string with leading and trailing whitespace characters removed.

Arguments

$string The string to trim.

Returns

The specified string with whitespace trimmed.

function StringIsAlphabetic($string as string) as integer

Returns whether the specified string contains only alphabetic characters.

Arguments

$string A string.

Returns

1 if the string contains only alphabetic characters. 0 otherwise.

function StringIsInteger($string as string) as integer

Returns whether the specified string represents an integer value.

Arguments

$string A string.

Returns

1 if the string represents an integer. 0 otherwise.

function StringIsReal($string as string) as integer

Returns whether the specified string represents a real value.

Arguments

$string A string.

Returns

1 if the string represents a real. 0 otherwise.

function StringIsWhitespace($string as string) as integer

Returns whether the specified string contains only whitespace characters.

Arguments

$string A string.

Returns

1 if the string contains only whitespace characters. 0 otherwise.