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.
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:
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:
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:
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:
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:
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):
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:
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.
Skipping spaces (only tab and new line delimiters)
The Field family of functions performs all of the same operations as the Word family of functions, except they only use tabs and new lines as field delimiters. For example, put the following function at the end of the game/scripts/client/client.cs
script file:
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:
The following will be output to the console:
With the Field family of functions, any field that contains spaces is treated as a single field.
Skipping spaces and tabs (only new line delimiters)
The Record family of functions performs all of the same operations as the Word family of functions, except they only use new lines as field delimiters. For example, put the following function at the end of the game/scripts/client/client.cs
script file:
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:
The following will be output to the console:
In the console, the output above the caret (^
) symbol represents a tab. With the Record family of functions, any field that contains spaces and tabs is treated as a single field.