Upgrading to new-style Strings

From Adventure Game Studio | Wiki
Jump to navigationJump to search

So you've finally decided to upgrade. Upgrading to new-style Strings is easy to accomplish if you know how. This tutorial is designed to help you get your old-style scripts working with newer versions of AGS. Realistically speaking, if you have a large game it may not be a simple task to upgrade. If your game relies on plug-ins, it may not even be possible. Keeping this in mind, let's get ready to script!

Defining a new-style String

Defining a new-style String is a simple process, and is very much the same as defining an old-style String:

 string old_str; // old-style string
 String new_Str; // new-style String

There are some things we have to keep in mind when defining new-style Strings though:

  • New-style Strings have a capital 'S'! Old-style strings use a lower-case 's'.
  • New-style Strings are pointer based. The pointer is internally managed, however new-style Strings can still hold the value null. Remember that operating on null pointers will crash your game!
  • As long as it is non-global (i.e., it is within a function) new-style Strings can have a default value assigned at the same time as you declare the String. Note that if you don't define a default value (or if the String is global (outside of all functions)) then it will hold the value null.

Setting a value

Old-style strings used several global functions for setting their values. You could use StrCopy, StrCat, and StrFormat to name a few, all of which could be used to change the value of the string. New-style Strings no longer use these global functions. To set the value you simply use the equal sign (the assignment operator). So in comparison:

 string old_str;
 StrCopy(old_str, "This is some text!");
 String new_Str = "This is some text!";

Now the old-style string old_str and the new-style String new_Str will both contain the text "This is some text!" (Note: Text between quotes is referred to as a string-literal. This tutorial reserves the right to use this terminology at the author's discretion).

Comparing the functions

This section of the tutorial will list and compare the old-style functions with their new-style alternatives.

StrCaseComp -> String.CompareTo

StrCaseComp compared two strings in a case-insensitive manner.

 string old_str;
 StrCopy(old_str1, "dog");
 Display("%d", StrCaseComp(old_str1, "DoG")); // displays 0

The new-style function is String.CompareTo:

 String new_Str = "dog";
 Display("%d", new_Str.CompareTo("DoG")); // displays 0
 // new_Str.CompareTo("DoG") is the same as new_Str.CompareTo("DoG", false)

StrCat -> String.Append

StrCat joined two strings together.

 string old_str;
 StrCopy(old_str, "This is ");
 StrCat(old_str, "some text!");
 Display(old_str); // displays "This is some text!"

The new-style function is String.Append:

 String new_Str = "This is ";
 new_Str = new_Str.Append("some text!");
 Display(new_Str); // displays "This is some text!"

Note that the new String is returned from the function. String.Append does not modify the String.

StrComp -> String.CompareTo

StrComp compared two strings in a case-sensitive manner.

 string old_str;
 StrCopy(old_str, "dog");
 Display("%d", StrComp(old_str, "DoG")); // displays non-zero

The new-style function is String.CompareTo:

 String new_Str = "dog";
 Display("%d", new_Str.CompareTo("DoG", true)); // displays non-zero

Note that when doing case-sensitive comparisons, you can use the == and != (equal and not equal) operators instead:

 String new_Str = "dog";
 Display("%d", new_Str == "DoG"); // displays ZERO

Also note that the comparison operators return a boolean value unlike the comparison functions. The reason new_Str == "DoG" displays zero is because the comparison returns false which evaluates as zero numerically. This is important because this is essentially the opposite of StrComp and String.CompareTo.

StrContains -> String.Contains

StrContains checked if a string contained another string.

 string old_str;
 StrCopy(old_str, "One, two, three");
 Display("%d", StrContains(old_str, "One")); // displays 0

The new-style function is String.Contains:

 String new_Str = "One, two, three";
 Display("%d", new_Str.Contains("One")); // displays 0

Note that this function is case-insensitive.

StrCopy -> Assignment operator

StrCopy assigned a value to a string.

 string old_str;
 StrCopy(old_str, "This is some text!");
 Display(old_str); // displays "This is some text!"

The new method of doing this is to use the assignment operator (the equal sign):

 String new_Str = "This is some text!";
 Display(new_Str); // displays "This is some text!"

StrFormat -> String.Format

StrFormat was used to format strings, especially for inserting variables into the string.

 int var = 5;
 string old_str;
 StrFormat(old_str, "%d", var);
 Display(old_str); // displays "5"

The new-style function is String.Format:

 int var = 5;
 String new_Str = String.Format("%d", var);
 Display(new_Str); // displays "5"

Note that this function is static, i.e., you call it directly from the String type, not from a String variable. Also this function does not modify the value of a String, rather it returns the new String.

This function can also be used to convert old-style strings into new-style Strings:

 string old_str;
 StrCopy(old_str, "This is some text!");
 String new_Str = String.Format("%s", old_str);

new_Str will now hold the value of the old-style string old_str.

StrGetCharAt -> String.Chars

StrGetCharAt returned the character at a given position in the string.

 string old_str;
 StrCopy(old_str, "This is some text!");
 Display("%c", StrGetCharAt(old_str, 5)); // displays 'i'

New-style Strings use the String.Chars array:

 String new_Str = "This is some text!";
 Display("%c", new_Str.Chars[5]); // displays 'i'

StringToInt -> String.AsInt

StringToInt converted a string into an integer.

 string old_str;
 StrCopy(old_str, "5");
 int var = StringToInt(old_str); // var == 5

New-style Strings use the String.AsInt property:

 String new_Str = "5";
 int var = new_Str.AsInt; // var == 5

StrLen -> String.Length

StrLen returned the length of the string in characters.

 string old_str;
 StrCopy(old_str, "This is some text!");
 Display("%d", StrLen(old_str)); // displays 18

New-style Strings use the String.Length property:

 String new_Str = "This is some text!";
 Display("%d", new_Str.Length)); // displays 18

StrSetCharAt -> String.ReplaceCharAt

StrSetCharAt replaced the character at a given index in a string.

 string old_str;
 StrCopy(old_str, "Tiis is some text!");
 StrSetCharAt(old_str, 1, 'h');
 Display(old_str); // displays "This is some text!"

The new-style function is String.ReplaceCharAt:

 String new_Str = "Tiis is some text!";
 new_Str = new_Str.ReplaceCharAt(2, 'h');
 Display(new_Str); // displays "This is some text!"

Note that this function does not modify the String, but returns the new String instead.

StrToLowerCase -> String.LowerCase

StrToLowerCase converted a string to all lower-case characters.

 string old_str;
 StrCopy(old_str, "HeLLo wOrlD!");
 StrToLowerCase(old_str);
 Display(old_str); // displays "hello world!"

The new-style function is String.LowerCase:

 String new_Str = "HeLLo wOrlD!";
 new_Str = new_Str.LowerCase();
 Display(new_Str); // displays "hello world!"

Note that this function does not modify the String, but returns the new String instead.

StrToUpperCase -> String.UpperCase

StrToUpperCase converted a string to all upper-case characters.

 string old_str;
 StrCopy(old_str, "HeLLo wOrlD!";
 StrToUpperCase(old_str);
 Display(old_str); // displays "HELLO WORLD!"

The new-style function is String.UpperCase:

 String new_Str = "HeLLo wOrlD!";
 new_Str = new_Str.UpperCase();
 Display(new_Str); // displays "HELLO WORLD!"

Note that this function does not modify the String, but returns the new String instead.

Other functions and properties

Below is a list and brief description of other functions and properties used by the new-style Strings.

String.AppendChar

String.AppendChar appends a single character to the end of a String. Note that this function does not modify the String, but returns the new String instead.

 String new_Str = "This is some text";
 new_Str = new_Str.AppendChar('!');
 Display(new_Str); // displays "This is some text!"

String.AsFloat

String.AsFloat returns the value of the String as a floating-point decimal value.

 String new_Str = "4.83";
 float var = new_Str.AsFloat; // var = 4.83

String.Copy

String.Copy returns a copy of the String. You shouldn't normally need to use this.

 String new_Str1 = "This is some text!";
 String new_Str2 = new_Str1.Copy();
 Display(new_Str2); // displays "This is some text!"

String.Substring

String.Substring returns a substring of the current String. Note that this function does not modify the String, but returns the new String instead.

 String new_Str = "This is some text!";
 new_Str = new_Str.Substring(8, 4);
 Display(new_Str); // displays "some"

String.Truncate

String.Truncate shortens the String to a given length. Note that this function does not modify the String, but returns the new String instead.

 String new_Str = "This is some text!";
 new_Str = new_Str.Truncate(12);
 Display(new_Str); // displays "This is some"

Function parameters

By this point you'll probably have noticed that any functions that take an old-style string as a parameter don't work with string-literals or new-style Strings any more. There are a two solutions to this problem:

  • If you still want to be able to use old-style strings with these functions, change the string parameter to a const string parameter:
 // function do_something(string param)
 // becomes
 function do_something(const string param)
  • If you want to use only new-style Strings and string-literals you can simply replace the parameter with a new-style String parameter:
 // function do_something(string param)
 // becomes
 function do_something(String param)

Note that if you use a new-style String parameter you can always pass in old-style strings using String.Format:

 do_something(String.Format("%s", old_str));

Also if you use a String parameter you have the ability to make the parameter optional.

Optional String parameters

Although it's not a supported method, you can make pointer-based parameters (e.g., String parameters) optional by supplying the default value of 0. Since this isn't an officially supported method there is no guarantee of forward-compatibility with this method, however it is possible with current versions of AGS:

 import function do_something(String param=0);

This will supply the parameter with a default value of null, so only do this if you have some method of handling null Strings!

See Also

Upgrading to AGS 2.71