GetTokenByPosition(string, string, int)

Return the i'th token in the string, by delimiter.

string GetTokenByPosition(
    string sString,
    string sDelimiter
    int nPos
);

Parameters

sString

The string to be split up into parts (tokens).

sDelimiter

The delimiter used to split up the string.

nPos

The position (=number) of the token that is to be returned.

Description

This function returns the i'th token within a given string. The string is split up into tokens, using a specified delimiter.

GetTokenByPosition() requires three arguments: The string that is to be split up into tokens (sString), the delimiter used to split up the string (sDelimiter) and the position (=number) of the token within the string (nPos).

The delimiter MUST be a string containing a single character.

The first token in the string is at position nPos = 0; the second at nPos = 1; etc. If there is no token at the specified position, an empty string "" is returned.

Remarks

Contrary to the description found in x0_i0_stringlib, the DELIMITER MUST be a SINGLE CHARACTER. Otherwise the tokenization process does not work as expected. The reason is that the function AdvanceToNextToken implicitly assumes that the delimiter has a length of 1. It is easy to modify that function in order to accommodate a delimiter consisting of multiple characters, by replacing any occurrence of 'nDelimPos+1' with 'nDelimPos+GetStringLength(stTok.sDelimiter)'. However, such a modification would result in functionality different from the Bioware provided functionality.

Keep in mind that the functions in x0_i0_stringlib are not very efficient. They do a lot of unnecessary string manipulations and unnecessary string parameter passing; string operations and string parameter passing (into or out of nwnscript functions) are amongst the most inefficient operations in nwnscript.

For the purpose of string tokenization by the functions provided in x0_i0_stringlib, a token is any substring (including empty substrings!) within the original string enclosed by the specified delimiter (e.g. every token has one delimiter to the left, one to the right and NO delimiters within). Any non-empty original string is treated as if it were enclosed within a pair of (virtual) delimiters to its left and right. Thus, unless the original string is empty, the number of tokens is always one higher than the number of delimiters contained within the original string. A non-empty string with no delimiters therefore consists out of one token, which is equal to the original string. An empty string has no tokens, although an empty token will be returned on request.

Example:

sString = "I|am|sloppy||programmer";
sDelimiter = "|";

Token[0] = "I";
Token[1] = "am";
Token[2] = "sloppy";
Token[3] = "";
Token[4] = "programmer";

sString contains five tokens and four delimiters.
GetTokenByPosition("I|am|sloppy||programmer", "|", 2) will return Token[2] = "sloppy"

Known Bugs

Contrary to the description found in the include file, the delimiter must be a single character (see remarks above).

Requirements

#include "x0_i0_stringlib"

Version

???

functions:	AdvanceToNextToken \| FindSubString \| GetNextToken \| GetNumberTokens \| GetStringTokenizer \| GetSubString \| HasMoreTokens
categories:	String Functions