GetToken

Description

Determines whether a token of the list in the delimiters parameter is present in a string.

Return value

The token found at position index of the string, as a string. If index is greater than the number of tokens in the string, returns an empty string.

Category

String functions

Syntax

GetToken(string, index [, delimiters ]) 

See also

Left, Right, Mid, SpanExcluding, SpanIncluding

Parameters

Parameter Description
string
A string or a variable that contains one. String in which to search.
index
Positive integer or a variable that contains one. The position of a token.
delimiters
A string or a variable that contains one. A delimited list of delimiters. Elements may consist of multiple characters.
Default list of delimiters: space character, tab character, newline character; or their codes: "chr(32)", "chr(9)", chr(10).
Default list delimiter: comma character.

Usage

The following examples show how this function works.

Example A: Consider the following code:

GetToken("red,blue:;red,black,tan:;red,pink,brown:;red,three", 2, ":;")

This function call requests element number 2 from the string, using the delimiter ";:". The output is as follows:

red,black,tan

Example B: Consider the following code:

<cfset mystring = "four," 
& #chr(32)# & #chr(9)# & #chr(10)# 
& ",five, nine,zero:;"
& #chr(10)# 
& "nine,ten:, eleven:;twelve:;thirteen," 
& #chr(32)# & #chr(9)# & #chr(10)# 
& ",four">
<cfoutput>
#mystring#<br><br>
</cfoutput>

The output is as follows:

four,
,five, nine,zero:;
nine,ten:, eleven:;twelve:;thirteen, 
,four

The gettoken function recognizes explicit spaces, tabs, or newline characters as the parameter delimiters (To specify a space character, the code is chr(32); a tab character, chr(9); and a newline character, chr(10).)

In the example string mystring, there is:

In the following call against mystring, no spaces are specified in delimiters (it is omitted), so the function uses the space character as the string delimiter:

<br>
<cfoutput>
gettoken(mystring, 3) is : #gettoken(mystring, 3)#
</cfoutput><br>

The output of this code is as follows:

gettoken(mystring, 3) is : nine,zero:;

The function finds the third delimiter, and returns the substring just before it that is between the second and third delimiter. This substring is "nine,zero:;".

Example C: Consider the following code:

<cfset mystring2 = "four," 
&#chr(9)# & #chr(10)# 
& ",five,nine,zero:;" 
& #chr(10)# 
& "nine,ten:,eleven:;twelve:;thirteen,"
& #chr(9)# & #chr(10)# & ",four">
<cfoutput>
#mystring2#<br>
</cfoutput>

The output is as follows:

four,
,five,nine,zero:; 
nine,ten:,eleven:;twelve:;thirteen, 
,four

The following is a call against mystring2:

<cfoutput>
gettoken(mystring2, 2) is : #gettoken(mystring2, 2)#
</cfoutput> 

The output is as follows:

gettoken(mystring2, 2) is : ,five,nine,zero:;

The function finds the second delimiter, and returns the substring just before it that is between the first and second delimiter. This substring is ",five,nine,zero:;".

Example

<h3>GetToken Example</h3>
<cfif IsDefined("FORM.yourString")>
<!--- set delimiter --->
<cfif FORM.yourDelimiter is not "">
    <cfset yourDelimiter = FORM.yourDelimiter>
  <cfelse>
    <cfset yourDelimiter = " ">
</cfif>
<!--- check whether number of elements in list is greater than or 
equal to the element sought to return --->
<cfif ListLen(FORM.yourString, yourDelimiter) GTE FORM.returnElement>
  <cfoutput>
  <p>Element #FORM.ReturnElement# in #FORM.yourString#,
  delimited by "#yourDelimiter#"
  <br>is:#GetToken(FORM.yourString, FORM.returnElement, yourDelimiter)#
  </cfoutput>
...

Comments