– Common Function Library Project

ListGetAtIncNulls(list, position[, delimiters])

Last updated September 29, 2003


Tom Litt

Version: 1 | Requires: CF5 | Library: StrLib

Will retrieve item in position-th item of list, counting empty-strings are proper list elements.

Return Values:
Returns a string.


<cfset TestList = "1|2|3||5">
List #TestList# has the following elements.<br>
<cfloop from="1" to="#ListLenIncNulls(TestList,'|')#" index="element">
Element #element#: "#ListGetAtIncNulls(TestList,element,'|')#"<br>


Name Description Required
list List to parse. Yes
position Position to retrieve. Yes
delimiters List delimiters. Only one character allow. Defaults to a comma. No

Full UDF Source:

 * Get specific list element of list where empty strings are counted as elements.
 * @param list 	 List to parse. (Required)
 * @param position 	 Position to retrieve. (Required)
 * @param delimiters 	 List delimiters. Only one character allow. Defaults to a comma. (Optional)
 * @return Returns a string. 
 * @author Tom Litt ( 
 * @version 1, September 29, 2003 
function ListGetAtIncNulls(list,position) {
	// Set up. Test for third parameter.
	var delimiter = ",";
	var ReturnedString = "";
	var lengthOfList = 0;
	var LenOfReturned = 0;
	var FirstDelimPosition = 0;
	var PreDelimPlace = 0;
	var PostDelimPlace = 0;
	var loop = 0;
	if(ArrayLen(Arguments) GT 2) delimiter = left(arguments[3],1);

	position = Val(position);
	// We need to know the number of elements in our list [including nulls!]
	lengthOfList = val(len(list) - len(replace(list,delimiter,"","ALL")) + 1);
	// We will have various chunks of different condition logic, depending on 
	// List length, and where in the list we are requesting. There is some overlap
	// possible (e.g. in a list of length 1) so we are using IsReturnSetYet, to 
	// avoid running unnecessary code in these cases.

	// List is too short, return ""
	if(lengthOfList lt position) return ""; 	

	// List has only one element, e.g. no delimiters. Return entire string.
	if(lengthOfList eq 1) return list; 
	if(lengthOfList eq position) {
		// We are returning the last list element
		// This is all the characters to the right of the last delimiter
		lenOfReturned = find(delimiter,reverse(list)) - 1;
		// If the last character is not a delimiter, we have something to return
		if(lenOfReturned) return right(list,LenOfReturned);
		// If the last character is a delimiter, the last string is ""
		else return "";
	if(position eq 1) {
		// We can snoop out the first element as quickly as we did with the last
		FirstDelimPosition = find(delimiter,list);
		if(FirstDelimPosition GT 1) return left(list,FirstDelimPosition-1);
		// First character is a delimiter, so first element is the empty string
		else return "";

	// We are returning a middle list element
	// The nth list element is sandwiched between the n-1th 
	// delimiter and the nth delimiter.
	// First we must find where those delimiters are...
	// We will call them 'predelim' and 'postdelim'				
	if(lengthOfList gt position) {
		// If position is 1, this loop will not be looped over
		for(loop=1;loop lte position-1;loop=loop+1) { PreDelimPlace = Find(delimiter,list,PreDelimPlace+1); }
		PostDelimPlace= Find(delimiter,list,PreDelimPlace+1);
		// As a result of previous if statements it should not be possible 
		// for PreDelimPlace and PostDelimPlace to be either 0 or Len(list).
		// But they could be next to each other.
		if(PostDelimPlace-PreDelimPlace EQ 1) return "";
		else return mid(list,PreDelimPlace+1,PostDelimPlace-PreDelimPlace-1);
blog comments powered by Disqus


Latest Additions

Kevin Cotton added
May 5, 2016

Raymond Camden added
April 25, 2016

Chris Wigginton added
January 18, 2016

Gary Stanton added
November 19, 2015

Sebastiaan Naafs - van Dijk added
November 13, 2015

Created by Raymond Camden / Design by Justin Johnson