Upgrading to new-style Strings

From Adventure Game Studio | Wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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!

Retrieved from ‘https://www.adventuregamestudio.co.uk/w/index.php?title=Upgrading_to_new-style_Strings&oldid=11426’