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:
- A forced space between the substrings "four," and ",five"
- A literal space between "five," and "nine"
- A literal space between "ten:," and "eleven,"
- A forced space between "thirteen," and ",four"
|
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>
...
|