String functions

String functions

Append
AppendChar
CompareTo
Contains
Copy
Format
LowerCase
ReplaceCharAt
Substring
Truncate
UpperCase
AsInt property
Chars property
Length property

Append

(Formerly known as global function StrCat, which is now obsolete)

String.Append(string str2)

Appends the string STR2 to the end of the specified string, and returns the result.

NOTE: The new concatenated string is returned as a new string from this function; it does NOT modify the original string.

Example:

String mytext = "Hello";
mytext = mytext.Append("World");
Display(mytext);

will display "HelloWorld".

AppendChar

String.AppendChar(char extraChar)

Appends a single character to the end of the specified string, and returns the result.

NOTE: The new concatenated string is returned as a new string from this function; it does NOT modify the original string.

Example:

String mytext = "Hell";
mytext = mytext.AppendChar('o');
Display(mytext);

will display "Hello".

See Also: String.Append

CompareTo

(Formerly known as global function StrCaseComp, which is now obsolete)
(Formerly known as global function StrComp, which is now obsolete)

String.CompareTo(string str2, optional bool caseSensitive)

Compares the specified string to STR2. caseSensitive determines whether "Dog" and "dog" are equivalent; case sensitivity is off by default.

Returns 0 if the strings match, or non-zero if they don't.

Example:

String mytext = "Hello";
if (mytext.CompareTo("World") == 0) {
  Display("Strings match!");
}
else {
  Display("Strings don't match!");
}

will display "Strings don't match".

Contains

(Formerly known as global function StrContains, which is now obsolete)

String.Contains(string needle)

Checks to see if NEEDLE is contained within the specified string. Returns the character position of the match if it is, or -1 if it is not.

This function is not case sensitive; ie. testing "test string" for "sTRiN" would match.

Example:

String haystack = "The haystack had a needle in it somewhere.";
int result = haystack.Contains("a needle");

if (result == -1) {
  Display("The string didn't contain the needle.");
}
else {
  Display("a needle was found starting at character %d in the string.", result);
}

Copy

(Formerly known as global function StrCopy, which is now obsolete)

String.Copy()

Returns a new copy of the specified string. You should not normally need to use this, since strings can be assigned using the = operator.

Example:

String mystring = "This is a test string.";
String newstring = mystring.Copy();
Display(newstring);

will display "This is a test string".

Format

(Formerly known as global function StrFormat, which is now obsolete)

static String.Format(string fmt, ...)

Processes the string FMT in the same way as the Display function does but instead of displaying it on the screen, returns the result as a new string.

You can insert the value of variables into the message. For more information, see the string formatting section.

NOTE: This function is static, which means you do not call it on an existing string variable, but use String.Format() instead.

Example:

int health=10;
String text = String.Format("%d", health);

will create a text string containing "10".

See Also: Display

LowerCase

(Formerly known as global function StrToLowerCase, which is now obsolete)

String.LowerCase()

Returns a lower case version of the specified string.

NOTE: The new string is returned from this function; it does NOT modify the original string.

Example:

String mystring = "THIS is a test string";
String lowercased = mystring.LowerCase();
Display("Old: %s, new: %s", mystring, lowercased);

will display "Old: THIS is a test string, new: this is a test string".

See Also: String.UpperCase

ReplaceCharAt

(Formerly known as global function StrSetCharAt, which is now obsolete)

String.ReplaceCharAt(int index, char newChar)

Changes the character at INDEX in the string to NEWCHAR.

INDEX is the character index into the string (where 0 is the first character, and the last allowable value is the string's Length minus 1).

NOTE: The new string is returned from this function; it does NOT modify the original string.

Example:

String mystring = "Hello";
String changed = mystring.ReplaceCharAt(2, 'm');
Display("Old: %s, new: %s", newstring, changed);

will display "Old: Hello, new: Hemlo".

See Also: String.Chars

Substring

String.Substring(int index, int length)

Returns part of the string, starting from character index and length characters long.

index is the initial character index, where 0 is the first character and (Length - 1) is the last. length specifies how many characters to retrieve.

Example:

String mystring = "Hello World!";
String substring = mystring.Substring(3, 5);
Display("Original: %s, Substring: %s", mystring, substring);

will display "Original: Hello World!, Substring: lo Wo".

See Also: String.Append, String.Chars

Truncate

String.Truncate(int length)

Returns a version of the string that has been truncated down to length characters.

NOTE: The new string is returned from this function; it does NOT modify the original string.

Example:

String mystring = "Hello World!";
String truncated = mystring.Truncate(4);
Display("Original: %s, Truncated: %s", mystring, truncated);

will display "Original: Hello World!, Truncated: Hell".

See Also: String.Append, String.Substring

UpperCase

(Formerly known as global function StrToUpperCase, which is now obsolete)

String.UpperCase()

Returns an upper case version of the specified string.

NOTE: The new string is returned from this function; it does NOT modify the original string.

Example:

String mystring = "THIS is a test string";
String uppercased = mystring.UpperCase();
Display("Old: %s, new: %s", mystring, uppercased);

will display "Old: THIS is a test string, new: THIS IS A TEST STRING".

See Also: String.LowerCase

AsInt property

(Formerly known as global function StringToInt, which is now obsolete)

readonly int String.AsInt;

Converts the string into an integer, and returns that value. Returns zero if the string does not contain a number.

Example:

String text1, text2;
int number1,number2;
text1 = "53";
text2 = "Hello";
number1 = text1.AsInt;
number2 = text2.AsInt;

will set number1 value to 53 and number2 value to 0. This function is useful for processing strings input from the user.

NOTE: To convert an integer to a string, you can use the String.Format command.

See Also: Game.InputBox, String.Format

Chars property

(Formerly known as global function StrGetCharAt, which is now obsolete)

readonly char String.Chars[position];

Returns the character at POSITION within the string.

POSITION is the character index (where 0 is the first character, and the last allowable value is the Length minus 1).

If POSITION is outside the string, this function returns 0.

NOTE: The Chars array is read-only. If you want to change one of the characters in the string, use String.ReplaceCharAt.

Example:

String text = "This is my string.";
Display("The 4th character is: %c", text.Chars[3]);

will display "The 4th character is: s".

Length property

(Formerly known as global function StrLen, which is now obsolete)

readonly int String.Length;

Returns the length of the string, in characters.

Example:

String text = "This is my string.";
Display("Length: %d", text.Length);

will display "Length: 18".