– 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);


Latest Additions

Raymond Camden added
November 04, 2017

Leigh added
May 11, 2016

Raymond Camden added
May 10, 2016

Kevin Cotton added
May 05, 2016

Raymond Camden added
April 25, 2016

Created by Raymond Camden / Design by Justin Johnson