Torque 3D - Script Manual: Field Manipulators

TorqueScript

Main   Class List   Namespace List   Online

Field Manipulators
[Strings]

Functions to deal with whitespace-separated lists of values in strings. More...

Functions

string firstWord (string text)
 Return the first word in text.
string getField (string text, int index)
 Extract the field at the given index in the newline and/or tab separated list in text.
int getFieldCount (string text)
 Return the number of newline and/or tab separated fields in text.
string getFields (string text, int startIndex, int endIndex=-1)
 Extract a range of fields from the given startIndex onwards thru endIndex.
string getRecord (string text, int index)
 Extract the record at the given index in the newline-separated list in text.
int getRecordCount (string text)
 Return the number of newline-separated records in text.
string getRecords (string text, int startIndex, int endIndex=-1)
 Extract a range of records from the given startIndex onwards thru endIndex.
string getWord (string text, int index)
 Extract the word at the given index in the whitespace-separated list in text.
int getWordCount (string text)
 Return the number of whitespace-separated words in text.
string getWords (string text, int startIndex, int endIndex=-1)
 Extract a range of words from the given startIndex onwards thru endIndex.
string removeField (string text, int index)
 Remove the field in text at the given index.
string removeRecord (string text, int index)
 Remove the record in text at the given index.
string removeWord (string text, int index)
 Remove the word in text at the given index.
string restWords (string text)
 Return all but the first word in text.
string setField (string text, int index, string replacement)
 Replace the field in text at the given index with replacement.
string setRecord (string text, int index, string replacement)
 Replace the record in text at the given index with replacement.
string setWord (string text, int index, string replacement)
 Replace the word in text at the given index with replacement.

Detailed Description

Functions to deal with whitespace-separated lists of values in strings.

TorqueScript extensively uses strings to represent lists of values. The functions in this group simplify working with these lists and allow to easily extract individual values from their strings.

The list strings are segregated into three groups according to the delimiters used to separate invididual values in the strings:

  • Strings of words: Elements are separated by newlines (\n), spaces, or tabs (\t).
  • Strings of fields: Elements are sepaerated by newlines (\n) or tabs (\t).
  • Strings of records: Elements are separated by newlines (\n).

Aside from the functions here, another useful means to work with strings of words is TorqueScript's foreach$ statement.

foreach$ Statement


Function Documentation

string firstWord ( string  text  ) 

Return the first word in text.

Parameters:
text A list of words separated by newlines, spaces, and/or tabs.
Returns:
The word at index 0 in text or "" if text is empty.
Note:
This is equal to
getWord( text, 0 )
See also:
getWord
string getField ( string  text,
int  index 
)

Extract the field at the given index in the newline and/or tab separated list in text.

Fields in text must be separated by newlines and/or tabs.

Parameters:
text A list of fields separated by newlines and/or tabs.
index The zero-based index of the field to extract.
Returns:
The field at the given index or "" if the index is out of range.
Example:
getField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d"
See also:
getFields
getFieldCount
getWord
getRecord
int getFieldCount ( string  text  ) 

Return the number of newline and/or tab separated fields in text.

Parameters:
text A list of fields separated by newlines and/or tabs.
Returns:
The number of newline and/or tab sepearated elements in text.
Example:
getFieldCount( "a b" TAB "c d" TAB "e f" ) // Returns 3
See also:
getWordCount
getRecordCount
string getFields ( string  text,
int  startIndex,
int  endIndex = -1 
)

Extract a range of fields from the given startIndex onwards thru endIndex.

Fields in text must be separated by newlines and/or tabs.

Parameters:
text A list of fields separated by newlines and/or tabs.
startIndex The zero-based index of the first field to extract from text.
endIndex The zero-based index of the last field to extract from text. If this is -1, all fields beginning with startIndex are extracted from text.
Returns:
A string containing the specified range of fields from text or "" if startIndex is out of range or greater than endIndex.
Example:
getFields( "a b" TAB "c d" TAB "e f", 1 ) // Returns "c d" TAB "e f"
See also:
getField
getFieldCount
getWords
getRecords
string getRecord ( string  text,
int  index 
)

Extract the record at the given index in the newline-separated list in text.

Records in text must be separated by newlines.

Parameters:
text A list of records separated by newlines.
index The zero-based index of the record to extract.
Returns:
The record at the given index or "" if index is out of range.
Example:
getRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "c d"
See also:
getRecords
getRecordCount
getWord
getField
int getRecordCount ( string  text  ) 

Return the number of newline-separated records in text.

Parameters:
text A list of records separated by newlines.
Returns:
The number of newline-sepearated elements in text.
Example:
getRecordCount( "a b" NL "c d" NL "e f" ) // Returns 3
See also:
getWordCount
getFieldCount
string getRecords ( string  text,
int  startIndex,
int  endIndex = -1 
)

Extract a range of records from the given startIndex onwards thru endIndex.

Records in text must be separated by newlines.

Parameters:
text A list of records separated by newlines.
startIndex The zero-based index of the first record to extract from text.
endIndex The zero-based index of the last record to extract from text. If this is -1, all records beginning with startIndex are extracted from text.
Returns:
A string containing the specified range of records from text or "" if startIndex is out of range or greater than endIndex.
Example:
getRecords( "a b" NL "c d" NL "e f", 1 ) // Returns "c d" NL "e f"
See also:
getRecord
getRecordCount
getWords
getFields
string getWord ( string  text,
int  index 
)

Extract the word at the given index in the whitespace-separated list in text.

Words in text must be separated by newlines, spaces, and/or tabs.

Parameters:
text A whitespace-separated list of words.
index The zero-based index of the word to extract.
Returns:
The word at the given index or "" if the index is out of range.
Example:
getWord( "a b c", 1 ) // Returns "b"
See also:
getWords
getWordCount
getField
getRecord
int getWordCount ( string  text  ) 

Return the number of whitespace-separated words in text.

Words in text must be separated by newlines, spaces, and/or tabs.

Parameters:
text A whitespace-separated list of words.
Returns:
The number of whitespace-separated words in text.
Example:
getWordCount( "a b c d e" ) // Returns 5
See also:
getFieldCount
getRecordCount
string getWords ( string  text,
int  startIndex,
int  endIndex = -1 
)

Extract a range of words from the given startIndex onwards thru endIndex.

Words in text must be separated by newlines, spaces, and/or tabs.

Parameters:
text A whitespace-separated list of words.
startIndex The zero-based index of the first word to extract from text.
endIndex The zero-based index of the last word to extract from text. If this is -1, all words beginning with startIndex are extracted from text.
Returns:
A string containing the specified range of words from text or "" if startIndex is out of range or greater than endIndex.
Example:
getWords( "a b c d", 1, 2, ) // Returns "b c"
See also:
getWord
getWordCount
getFields
getRecords
string removeField ( string  text,
int  index 
)

Remove the field in text at the given index.

Fields in text must be separated by newlines and/or tabs.

Parameters:
text A list of fields separated by newlines and/or tabs.
index The zero-based index of the field in text.
Returns:
A new string with the field at the given index removed or the original string if index is out of range.
Example:
removeField( "a b" TAB "c d" TAB "e f", 1 ) // Returns "a b" TAB "e f"
See also:
removeWord
removeRecord
string removeRecord ( string  text,
int  index 
)

Remove the record in text at the given index.

Records in text must be separated by newlines.

Parameters:
text A list of records separated by newlines.
index The zero-based index of the record in text.
Returns:
A new string with the record at the given index removed or the original string if index is out of range.
Example:
removeRecord( "a b" NL "c d" NL "e f", 1 ) // Returns "a b" NL "e f"
See also:
removeWord
removeField
string removeWord ( string  text,
int  index 
)

Remove the word in text at the given index.

Words in text must be separated by newlines, spaces, and/or tabs.

Parameters:
text A whitespace-separated list of words.
index The zero-based index of the word in text.
Returns:
A new string with the word at the given index removed or the original string if index is out of range.
Example:
removeWord( "a b c d", 2 ) // Returns "a b d"
See also:
removeField
removeRecord
string restWords ( string  text  ) 

Return all but the first word in text.

Parameters:
text A list of words separated by newlines, spaces, and/or tabs.
Returns:
text with the first word removed.
Note:
This is equal to
getWords( text, 1 )
See also:
getWords
string setField ( string  text,
int  index,
string  replacement 
)

Replace the field in text at the given index with replacement.

Fields in text must be separated by newlines and/or tabs.

Parameters:
text A list of fields separated by newlines and/or tabs.
index The zero-based index of the field to replace.
replacement The string with which to replace the field.
Returns:
A new string with the field at the given index replaced by replacement or the original string if index is out of range.
Example:
setField( "a b" TAB "c d" TAB "e f", 1, "g h" ) // Returns "a b" TAB "g h" TAB "e f"
See also:
getField
setWord
setRecord
string setRecord ( string  text,
int  index,
string  replacement 
)

Replace the record in text at the given index with replacement.

Records in text must be separated by newlines.

Parameters:
text A list of records separated by newlines.
index The zero-based index of the record to replace.
replacement The string with which to replace the record.
Returns:
A new string with the record at the given index replaced by replacement or the original string if index is out of range.
Example:
setRecord( "a b" NL "c d" NL "e f", 1, "g h" ) // Returns "a b" NL "g h" NL "e f"
See also:
getRecord
setWord
setField
string setWord ( string  text,
int  index,
string  replacement 
)

Replace the word in text at the given index with replacement.

Words in text must be separated by newlines, spaces, and/or tabs.

Parameters:
text A whitespace-separated list of words.
index The zero-based index of the word to replace.
replacement The string with which to replace the word.
Returns:
A new string with the word at the given index replaced by replacement or the original string if index is out of range.
Example:
setWord( "a b c d", 2, "f" ) // Returns "a b f d"
See also:
getWord
setField
setRecord


Copyright © GarageGames, LLC. All Rights Reserved.