When working with lists in TorqueScript, be it a list of scene object IDs or a set of Cartesian coordinates, we will invariably come across space-delimited strings. For example, calling the getPosition() method on a scene object will return a three-field string such as 13.4 -2.1 96.35 that represents the world distance along the x, y, and z axes, respectively.

TorqueScript provides a number of functions that allows us to access and manipulate the fields within space-delimited strings. In this recipe we will learn how to use these functions when working with string variables.

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com . If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager ( Project Manager.exe ) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

Start up our game under the My Projects directory and load the Empty Terrain level. Open the console using the tilde (~) key and enter the following at the bottom of the screen:

We are going to write a TorqueScript function that will parse a space-delimited string and output the results to the console. This is done as follows:

How it works...

The previous code walks us through all of the functions used to access and manipulate the variables that contain space-delimited fields. We will now examine each of these functions and learn how to make use of them.

After obtaining the player's world position, our first action in the previous example is to get the number of fields within the space-delimited string (the %position variable). This is done using the getWordCount() function that has the following form:

amount = getWordCount( string );

In this form, string is the space-delimited string that contains the number of fields we want to eventually parse. The getWordCount() function returns the number of fields counted. The previous code stores this value into the %count variable. If there are no fields in the string, then 0 is returned.

With the number of fields now known, we can retrieve the individual x, y, and z values of the %position variable based on an index. To do this we use the getWord() function that has the following form:

field = getWord( string, index );

Here, the string parameter is the space-delimited string to parse, and the index parameter is the field number to retrieve. The getWord() function returns a string containing the single requested field. If the field index does not exist within the passed-in string, an empty string is returned.

The next action performed in the example code is to retrieve more than one field at a time. Specifically, the code extracts the x and y values from the player's position (the first and second field). We use the getWords() function to retrieve more than one field, which has the following form:

fields = getWords( string, startIndex, [endIndex] );

Here, the string parameter is the space-delimited string to parse, the startIndex parameter is the start of the range to retrieve, and the optional endIndex parameter is the end of the field range. If endIndex is not provided or has a value of -1 , then all of the fields at the end of the string are returned.

The getWords() function returns a string containing all of the requested fields. If none of the requested fields exist within the passed-in string, an empty string is returned.

The example code then goes on to manipulate the %position variable by changing its z value (the third field). This is done with the setWord() function that has the following form:

result = setWord( string, index, replacement );

Here, the string parameter is the space-delimited string to modify, the index parameter is the field index in the string to modify, and the replacement parameter is the string used to replace the current value of the field. The setWord() function returns a new string with the modifications and doesn't change the passed-in string. If we wanted to modify the original variable, we would just use the same variable name for the return value as we did for the passed-in string. For example, consider the following code:

%position = setWord(%position, 2, "0");

The new string will essentially replace the previous string stored in %position .

If the index passed-in to setWord() is larger than the number of fields in the given string, the returned string is padded with empty fields to make up the difference, essentially appending the replacement string on to the end. For example, the following code would print a count of six to the console (the fifth index accesses the sixth field):

%val1 = "1 2 3"; %val2 = setWord( %val1, 5, "4"); echo( getWordCount( %val2 ) );

The final action in the example code removes a field from the string variable. This is done using the removeWord() function that has the following form:

result = removeWord( string, index );

Here, the string parameter is the space-delimited string to modify, and the index parameter is the field index in the string to remove. The removeWord() function returns a new string with the modifications and doesn't change the passed-in string. If the given field index does not exist within the string, the original string is returned unchanged.