UDN
Search public documentation:

StringsInUnrealScript
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > UnrealScript > Strings In UnrealScript

Strings In UnrealScript


Overview


The Object and Actor classes contain many operators and functions for performing actions with or on strings in UnrealScript. This document details these operators and functions.

Operators


$ (dollar sign)

string $ ( coerce string A, coerce string B )

The $ operator takes two strings, A and B, and concatenates them. If either A or B are not strings, their values will attempt to be converted to string values.

Example:

`log("Unreal"$"Script"); //prints "UnrealScript"

$=

string $= ( out string A, coerce string B )

The $= operator takes two strings, A and B, concatenates them, and assigns the resulting string to the first. If B is not a string, its value will attempt to be converted to a string value.

Example:

MyString = "Unreal";
MyString $= "Script"; // MyString contains "UnrealScript"

@ (at)

string @ ( coerce string A, coerce string B )

The @ operator takes two strings, A and B, and concatenates them placing a space between the two. If either A or B are not strings, their values will attempt to be converted to string values.

Example:

log("Unreal"@"Engine"); //prints "Unreal Engine"

@=

string @= ( out string A, coerce string B )

The @= operator takes two strings, A and B, concatenates them placing a space between the two, and assigns the resulting string to the first. If B is not a string, its value will attempt to be converted to a string value.

Example:

MyString = "Unreal";
MyString @= "Engine"; // MyString contains "Unreal Engine"

< (less-than)

bool < ( string A, string B )

The < operator takes two strings, A and B, and returns true if the first string is alphabetically before the second string. Note that capital letters are always alphabetically before lower case letters; consider Caps if case does not matter.

Example:

("Monkey" < "Robot") //this is TRUE.

> (greater-than)

bool > ( string A, string B )

The > operator takes two strings, A and B, and returns true if the first string is alphabetically after the second string. Note that capital letters are always alphabetically before lower case letters; consider Caps if case does not matter.

Example:

("Batman" > "Aquaman") //this is TRUE.

<= (less-than-or-equal-to)

bool <= ( string A, string B )

The <= operator takes two strings, A and B, and returns true if the first string is alphabetically before or the same as the second string. Note that capital letters are always alphabetically before lower case letters; consider Caps if case does not matter.

Example:

("Monkey" <= "Robot")  //this is TRUE.
("Monkey" <= "Monkey") //this is TRUE.

>= (greater-than-or-equal-to)

bool >= ( string A, string B )

The >= operator takes two strings, A and B, and returns true if the first string is alphabetically after or the same as the second string. Note that capital letters are always alphabetically before lower case letters; consider Caps if case does not matter.

Example:

("Monkey" >= "Robot")  //this is FALSE.
("Monkey" >= "Monkey") //this is TRUE.

== (equal-equal)

bool == ( string A, string B )

The == operator takes two strings, A and B, and returns true if the strings are the same. Note that this is a case sensitive compare.

Example:

("Monkey" == "Robot")  //this is FALSE.
("Monkey" == "Monkey") //this is TRUE.
("Monkey" == "monkey") //this is FALSE.

!= (not-equal)

bool != ( string A, string B )

The != operator takes two strings, A and B, and returns true if the strings are NOT the same. Note that this is a case sensitive compare.

Example:

("Monkey" != "Robot")  //this is TRUE.
("Monkey" != "Monkey") //this is FALSE.
("Monkey" != "monkey") //this is TRUE.

~= (tilde-equal)

bool ~= ( string A, string B )

The ~= operator takes two strings, A and B, and returns true if the strings are the same regardless of case.

Example:

("Monkey" ~= "Robot")  //this is FALSE.
("Monkey" ~= "Monkey") //this is TRUE.
("Monkey" ~= "monkey") //this is TRUE.

-= (minus-equal)

string -= ( out string A, coerce string B );

The -= operator removes all occurences of B from A and assigns the result to A. This is a case-sensitive operation. If B is not a string, its value will attempt to be converted to a string value.

Example:

MyString = "test: this is a test";
MyString -= "test";
log(MyString); // prints: ": this is a ";

Object Functions


Len

int Len ( coerce string S )

Returns the length of a string.

Example:

Len("this"); //returns 4;

InStr

int InStr ( coerce string S, coerce string t )

The InStr() function returns the position of the first occurrence of substring t in S. If the substring is not found, InStr returns -1. Note that the search is case sensitive and so consider calling Caps before using InStr if you are not concerned about case. If either S or t are not strings, their values will attempt to be converted to string values.

Example:

InStr("These PANTS rock!", "PANTS"); //returns 6
InStr("These PANTS rock!", "pants"); //returns -1
InStr( Caps("These PANTS rock!"), Caps("pants") ); //returns 6

Mid

string Mid ( coerce string S, int i, optional int j )

The Mid() function generates a substring of S by starting at character i and copying j characters. If j is omitted, the rest of the string is copied. i is clamped between 0 and the length of the string. j is clamped between i and the length of the string. If S is not a string, its value will attempt to be converted to a string value.

Example:

Mid("These PANTS rock!", 6, 5); //returns "PANTS"
Mid("These PANTS rock!", 6); //returns "PANTS rock!"

Left

string Left ( coerce string S, int i )

The Left() function returns the i leftmost characters in the given string S. This returns the string to the left of index i but not including that character. If S is not a string, its value will attempt to be converted to a string value.

Example:

Left("These PANTS rock!", 5); //returns "These"

Right

string Right ( coerce string S, int i )

The Right() function returns the i rightmost characters in the given string S. If S is not a string, its value will attempt to be converted to a string value.

Example:

Right("These PANTS rock!", 5); //returns "rock!"

Caps

string Caps ( coerce string S )

The Caps() function returns the capitalized version of the given string S. If S is not a string, its value will attempt to be converted to a string value.

Example:

Caps("wooo"); //returns "WOOO"

Locs

string Locs ( coerce string S )

The Locs() function returns the lowercase version of the given string S. If S is not a string, its value will attempt to be converted to a string value.

Example:

Locs("WoOo"); //returns "wooo"

Chr

string Chr ( int i )

The Chr() function returns the string representation of the given int. This can be anything in the Unicode range 0 - 65535.

Example:

Chr(65); //returns "A"

Asc

int Asc ( string S )

The Asc() function returns the numeric Unicode representation of the first letter of the given string S.

Example:

Asc("A"); //returns 65

Repl

string Repl ( coerce string Src, coerce string Match, coerce string With, optional bool bCaseSensitive )

The Repl() function replaces all occurences of Match with With in Src. If Src, Match, or With are not strings, their values will attempt to be converted to string values.

Example;

Repl("This is a test", "is", "was"); // produces "Thwas was a test";
Repl("Two be or not two be", "two", "to", true); // returns "Two be or not to be"
Repl("Two be or not two be", "two", "to", false); // returns "to be or not to be"

Split

static final function string Split(coerce string Text, coerce string SplitStr, optional bool bOmitSplitStr)

The Split() function splits Text on the first occurrence of SplitStr and returns the remaining part of Text. If bOmitSplitStr is TRUE, the SplitStr is ommitted from the remaining portion of Text that is returned. Otherwise, it is included. If Text or SplitStr are not strings, their values will attempt to be converted to string values.

Example:

Split("Unreal Engine uses UnrealScript as its scripting language", "scripting", false); // returns "scripting language"
Split("Unreal Engine uses UnrealScript as its scripting language", "scripting", true); // returns " language"

GetRightMost

string GetRightMost( coerce string Text )

The GetRightMost() function gets the substring of Text found after the right-most '_' character, such as the number from an actor name. If Text is not a string, its value will attempt to be converted to a string value.

Example:

GetRightMost("CoverLink_45"); // returns "45"

JoinArray

JoinArray(array<string> StringArray, out string out_Result, optional string delim = ",", optional bool bIgnoreBlanks = true)

The JoinArray() function creates a single string from the StringArray array of strings, using the delim delimiter specified, and assigns the resulting string to out_Result. If bIgnoreBlanks is TRUE, elements in the StringArray which are empty will be ignored.

Example:

Maps[0] = "Deck";
Maps[1] = "Necropolis";
Maps[2] = "Sandstorm";
Maps[2] = "Sanctuary";
JoinArray(Maps, MapString); // MapString contains "Deck,Necropolis,Sandstorm,Sanctuary"

ParseStringIntoArray

ParseStringIntoArray(string BaseString, out array<string> Pieces, string Delim, bool bCullEmpty)

The ParseStringIntoArray() function breaks up a string into elements of a string array, using the Delim delimiter specified, and assigns the resulting array to Pieces. If bCullEmpty is TRUE, when the delimiter occurrs in immediate succession, the empty element normally created by this case will not be added to the array.

Example:

ParseStringIntoArray("Deck,Necropolis,,Sandstorm,Sanctuary", Maps, ",", false); // Maps contains {Deck, Necropolis, , Sanstorm, Sanctuary}
ParseStringIntoArray("Deck,Necropolis,,Sandstorm,Sanctuary", Maps, ",", true); // Maps contains {Deck, Necropolis, Sanstorm, Sanctuary}

SplitString

array<string> SplitString( string Source, optional string Delimiter=",", optional bool bCullEmpty )

The SplitString() function is a wrapper for splitting a string into an array of strings using the ParseStringIntoArray() function. The only real difference is the array is the return value of the SplitString() function instead of an out parameter.

Example:

SplitString("Deck,Necropolis,,Sandstorm,Sanctuary", ",", false); // returns array of {Deck, Necropolis, , Sanstorm, Sanctuary}
ParseStringIntoArray("Deck,Necropolis,,Sandstorm, Maps, ",", false); // Maps contains {Deck, Necropolis, , Sanstorm, Sanctuary}

Actor Functions


ReplaceText

function ReplaceText(out string Text, string Replace, string With)

The ReplaceText() function is similar to the Repl() function except that the result will be assigned to the input string Str.

Example:

Str = "This is a test";
ReplaceText(Str, "is", "was"); // Str contains "Thwas was a test";

Str = "Two be or not two be";
ReplaceText(Str, "two", "to"); // Str contains "Two be or not to be"

GetItemName

String GetItemName( string FullName )

The GetItemName() function accepts a "Package.Item" string and returns the "Item" part of it.

Example:

GetItemName(string(self)); // returns the class name
GetItemName("Package.Group.bla.Item"); // return "Item"

Special Considerations


String Concatenation and Assignment

You'll often see script code that looks like this:

for ( i = 0; i < Count; i++ )
{
      if ( MyString != "" )
      {
            MyString = MyString + ", ";
      }
      MyString = MyString + NextArrayValue[i];
}

There are currently two string operators for performing string concatenation and assignment:

native(322) static final operator(44) string $= ( out  string A, coerce string B );
native(323) static final operator(44) string @= ( out  string A, coerce string B);

The above code could be rewritten to look like:

for ( i = 0; i < Count; i++ )
{
      if ( MyString != "" )
      {
            MyString $= ", ";
      }
      MyString $= NextArrayValue[i];
}

The reason is that the $= operator is faster!

Here is what is actually happening for each version:

MyString = MyString + NextArrayValue[i];

  1. Evaluate the left side; look up the address for the MyString variable.
  2. Evaluate the right side; invokes the + operator (execString_Concat)
  3. Look up the address of the MyString variable; copy its value into a temporary buffer for use by the + operator.
  4. Look up the address of the NextArrayValue (execArrayElement); copy its value into a temporary buffer for use by the + operator.
  5. Add the two temporary buffers together; copy that string into MyString.

MyString $= NextArrayValue[i];

  1. Look up the address for the MyString variable.
  2. Look up the address for the NextArrayValue[i] variable. Append the value directly to MyString.