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!

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:

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.

As with the setWord() function, if we want to modify the original variable, we would need to pass it in as the string parameter as well as use it to store the result. This is done in the example code with the %position variable.

While space-delimited strings are the most common type of list we will come across in TorqueScript, spaces are not the only way to delimit a string. Tabs and new lines may also be used. We could use tab delimiters when we want the fields to contain spaces, and new line delimiters when we want the fields to contain spaces or tabs.

The whole Word family of functions we just explored (getWord() and so on) actually works with more than just spaces. They treat all the spaces, tabs, and new lines as valid delimiters. But what if we don't want to count spaces as a delimiter, such as with a list of peoples' combined first and last names ("John Smith")? There are two other families of functions that narrow the scope of what is a valid delimiter: Field and Record.

function operateOnFields2()
{
   // Build up a list of tab delimited name
   %list = "John Smith" TAB "Mary Contrary" TAB "Fido";
   
   // Get the number of tab delimited fields
   %count = getFieldCount(%list);
   
   // Print out a list of fields by index
   for (%i=0; %i<%count; %i++)
   {
      echo("Field " @ %i @ ": " @ getField(%list, %i));
   }
}

operateOnFields2();

==>operateOnFields2();
Field 0: John Smith
Field 1: Mary Contrary
Field 2: Fido

function operateOnFields3()
{
   // Build up a list of new line delimited items
   %list = "0" TAB "First item" NL
           "1" TAB "Second item" NL
           "2" TAB "Third item";
   
   // Get the number of tab delimited fields
   %count = getRecordCount(%list);
   
   // Print out a list of fields by index
   for (%i=0; %i<%count; %i++)
   {
      echo("Field " @ %i @ ": '" 
           @ getRecord(%list, %i) @ "'");
   }
}

operateOnFields3();

==>operateOnFields3();
Field 0: '0^First item'
Field 1: '1^Second item'
Field 2: '2^Third item'