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