CFLib.org – Common Function Library Project

Description:
It mimics the behaviour of php "substr", enclosing mid, left and right functionalities into a single function and adding some extra-functionality and trick. For instance: - substr("abcdef", -2) is the same as right("abcdef", 2), - substr("abcdef", 1, 3) is the same as left("abcdef", 3), - substr("abcdef", 2, 4) is the same as mid("abcdef", 2, 4) At the same time, it permits things like - substr("abcdef", 2) instead of mid("abcdef", 2, len("abcdef")-2) - substr("abcdef", -2, 1) to say "start 2 chars before the end of the string, and take 1 char." - substr("abcdef", -4, -1) to say "start 4 chars before the end of the string, and throw away the last char." It returns an empty string in case of inconsistent indexes.

Return Values:
Returns a string.

Example:

<cfset buffer = "Sailors">
<cfoutput>
substr(buffer, 2) = #substr(buffer, 2)#<br>
substr(buffer, -2) = #substr(buffer, -2)#<br>
substr(buffer, 1, 3) = #substr(buffer, 1, 3)#<br>
substr(buffer, 2, 4) = #substr(buffer, 2, 4)#<br>
substr(buffer, 2, -3) = #substr(buffer, 2, -3)#<br>
substr(buffer, -4, 2) = #substr(buffer, -4, 2)#<br>
substr(buffer, -4, -1) = #substr(buffer, -4, -1)#<br>
</cfoutput>

Parameters:

Full UDF Source:

/**
 * Returns the substring of a string. It mimics the behaviour of the homonymous php function so it permits negative indexes too.
 * 
 * @param buf      The string to parse. (Required)
 * @param start      The start position index. If negative, counts from the right side. (Required)
 * @param length      Number of characters to return. If not passed, returns from start to end (if positive start value). (Optional)
 * @return Returns a string. 
 * @author Rudi Roselli Pettazzi (rhodion@tiscalinet.it) 
 * @version 2, July 2, 2002 
 */
function SubStr(buf, start) {
    // third argument (optional)
    var length = 0;
    var sz = 0;
        
    sz = len(buf);
    
    if (arrayLen(arguments) EQ 2) {

        if (start GT 0) {
            length = sz;
        } else if (start LT 0) {
            length = sz + start;
            start = 1;
        }
    
    } else {
    
        length = Arguments[3];
        if (start GT 0) {
            if (length LT 0)   length = 1+sz+length-start;
        } else if (start LT 0) {
            if (length LT 0) length = length-start;
            start = 1+sz+start;
            
        }
    } 
    
    if (isNumeric(start) AND isNumeric(length) AND start GT 0 AND length GT 0) return mid(buf, start, length);
    else return "";
}