Upgrading to new-style Strings: Difference between revisions
*>Monkey 05 06 m (→Eek! TIPO! :P) |
*>Monkey 05 06 |
||
Line 72: | Line 72: | ||
Display("%d", new_Str.CompareTo("DoG", true)); // displays non-zero | Display("%d", new_Str.CompareTo("DoG", true)); // displays non-zero | ||
Note that when doing case-sensitive comparisons, you can use the == | Note that when doing case-sensitive comparisons, you can use the == and != (equal and not equal) operators instead: | ||
String new_Str = "dog"; | String new_Str = "dog"; |
Revision as of 06:16, 15 June 2007
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 non-zero
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!