String Manipulation

In this section we will briefly cover some of the most common string manipulation techniques, such as string concatenation and comparisons.

(For more information on the string functions available to you in AutoPlay Media Studio, see Program Reference / Actions / String in the online help.)

Concatenating Strings

We have already covered string concatenation, but it is well worth repeating. The string concatenation operator is two periods in a row (..). For example:

FullName = "Bo".." Derek";  -- FullName is now "Bo Derek"

-- You can also concatenate numbers into strings
DaysInYear = 365;
YearString = "There are "..DaysInYear.." days in a year.";

Note that you can put spaces on either side of the dots, or on one side, or not put any spaces at all. For example, the following four lines will accomplish the same thing:

foo = "Hello " .. user_name;
foo = "Hello ".. user_name;
foo = "Hello " ..user_name;
foo = "Hello "..user_name;

Comparing Strings

Next to concatenation, one of the most common things you will want to do with strings is compare one string to another. Depending on what constitutes a “match,” this can either be very simple, or just a bit tricky.

If you want to perform a case-sensitive comparison, then all you have to do is use the equals operator (==). For example:

strOne = "Strongbad";
strTwo = "Strongbad";

if strOne == strTwo then
     Dialog.Message("Guess what?", "The two strings are equal!");
     Dialog.Message("Hmmm", "The two strings are different.");

Since the == operator performs a case-sensitive comparison when applied to strings, the above script will display a message box proclaiming that the two strings are equal.

If you want to perform a case-insensitive comparison, then you need to take advantage of either the String.Upper or String.Lower function, to ensure that both strings have the same case before you compare them. The String.Upper function returns an all-uppercase version of the string it is given, and the String.Lower function returns an all-lowercase version. Note that it doesn’t matter which function you use in your comparison, so long as you use the same function on both sides of the == operator in your if statement.

For example:

strOne = "Mooohahahaha";
strTwo = "MOOohaHAHAha";

if String.Upper(strOne) == String.Upper(strTwo) then
     Dialog.Message("Guess what?", "The two strings are equal!");
     Dialog.Message("Hmmm", "The two strings are different.");

In the example above, the String.Upper function converts strOne to “MOOOHAHAHAHA” and strTwo to “MOOOHAHAHAHA” and then the if statement compares the results. (Note: the two original strings remain unchanged.) That way, it doesn’t matter what case the original strings had; all that matters is whether the letters are the same.

Counting Characters

If you ever want to know how long a string is, you can easily count the number of characters it contains. Just use the String.Length function, like so:

twister = "If a wood chuck could chuck wood, how much";
num_chars = String.Length(twister);
Dialog.Message("That tongue twister has:", num_chars .. " characters!");

...which would produce the following dialog message:

You can also get the length of a string using the length operator #. For example, #"hey" would result in 3.

Finding Strings

Another common thing you’ll want to do with strings is to search for one string within another. This is very simple to do using the String.Find action.

For example:

strSearchIn = "Isn't it a wonderful day outside?";
strSearchFor = "wonder";

-- search for strSearchFor inside strSearchIn
nFoundPos = String.Find(strSearchIn, strSearchFor);

if nFoundPos ~= nil then
     -- found it!
     Dialog.Message("Search Result", strSearchFor ..
                    " found at position " .. nFoundPos);
     -- no luck
     Dialog.Message("Search Result", strSearchFor .. " not found!");

...would cause the following message to be displayed:

Tip: Try experimenting with different values for strSearchFor and strSearchIn.

Replacing Strings

One of the most powerful things you can do with strings is to perform a search and replace operation on them. The following example shows how you can use the String.Replace action to replace every occurrence of a string with another inside a target string.

strTarget = "There can be only one. Only one is allowed!";
strSearchFor = "one";
strReplaceWith = "a dozen";
strNewString = String.Replace(strTarget, strSearchFor, strReplaceWith);
Dialog.Message("After searching and replacing:", strNewString);

-- create a copy of the target string with no spaces in it
strNoSpaces = String.Replace(strTarget, " ", "");
Dialog.Message("After removing spaces:", strNoSpaces);

The above example would display the following two messages:

Extracting Strings

There are three string functions that allow you to “extract” a portion of a string, rather than copying the entire string itself. These functions are String.Left, String.Right, and String.Mid.

String.Left copies a number of characters from the beginning of the string. String.Right does the same, but counting from the right end of the string instead. String.Mid allows you to copy a number of characters starting from any position in the string.

You can use these functions to perform all kinds of advanced operations on strings.

Here’s a basic example showing how they work:

strOriginal = "It really is good to see you again.";

-- copy the first 13 characters into strLeft
strLeft = String.Left(strOriginal, 13);

-- copy the last 18 characters into strRight
strRight = String.Right(strOriginal, 18);

-- create a new string with the two pieces
strNeo = String.Left .. "awesome" .. strRight .. " Whoa.";

-- copy the word "good" into strMiddle
strMiddle = String.Mid(strOriginal, 13, 4);

Converting Numeric Strings into Numbers

There may be times when you have a numeric string, and you need to convert it to a number.

For example, if you have an input field where the user can enter their age, and you read in the text that they typed, you might get a value like “31”. Because they typed it in, though, this value is actually a string consisting of the characters “3” and “1”.

If you tried to compare this value to a number, you would get a syntax error saying that you attempted to compare a number with a string.

For example, the following script:

age = "31";
if age > 18 then
     Dialog.Message("", "You're older than 18.");

...would produce the following error message:

The problem in this case is the line that compares the contents of the variable “age” with the number 18:

if age > 18 then

This generates an error because age contains a string, and not a number. The script engine doesn’t allow you to compare numbers with strings in this way. It has no way of knowing whether you wanted to treat age as a number, or treat 18 as a string.

The solution is simply to convert the value of age to a number before comparing it. There are two ways to do this. One way is to use the String.ToNumber function.

The String.ToNumber function translates a numeric string into the equivalent number, so it can be used in a numeric comparison.

age = "31";
if String.ToNumber(age) > 18 then
     Dialog.Message("", "You're older than 18.");

The other way takes advantage of the scripting engine’s ability to convert numbers into strings when it knows what your intentions are. For example, if you’re performing an arithmetic operation (such as adding two numbers), the engine will automatically convert any numeric strings to numbers for you:

age = "26" + 5; -- result is a numeric value

The above example would not generate any errors, because the scripting engine understands that the only way the statement makes sense is if you meant to use the numeric string as a number. As a result, the engine automatically converts the numeric string to a number so it can perform the calculation.

Knowing this, we can convert a numeric string to a number without changing its value by simply adding 0 to it, like so:

age = "31";
if (age + 0) > 18 then
     Dialog.Message("", "You're older than 18.");

In the preceding example, adding zero to the variable gets the engine to convert the value to a number, and the result is then compared with 18. No more error.