GetToken

Description

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

Returns

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

Function 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> ...

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7