CFLib.org – Common Function Library Project

ArraySplice(array, index, howMany)

Last updated July 24, 2012

author

Joshua Miller

Version: 1 | Requires: CF8 | Library: CFMLLib

Description:
Changes the content of an array, adding new elements while removing old elements. As well as the specified named arguments, takes any number of optional arguments which are spliced into the array at `index`. If passing these optional arguments, all arguments must be specified positionally, not as name/value pairs. Differs from its Javascript counterpart in that it returns the modified array, rather than updating the array argument and returning an array of the removed elements. This is due to limitations in ColdFusion's array support.

Return Values:
The updated array.

Example:

<cfscript>
aOriginal = ["Original 1", "Original 2", "Original 3", "Original 4"];
writeDump(aOriginal);

aResult = arraySplice(aOriginal, 3, 0, "Insert 1", "Insert 2");
writeDump(aResult);
</cfscript>

Parameters:

Name Description Required
array The array to splice. Yes
index Index at which to start changing the array. If negative, will begin that many elements from the end. Yes
howMany An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element. If no howMany parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after index are removed. Yes

Full UDF Source:

/**
 * Mimics the functionality of JavaScript Splice() method
(https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/splice)
 * version 0.1 by Joshua Miller
 * version 1.0 by Adam Cameron - reworking so it more closely emulates its Javascript namesake
 * 
 * @param array 	 The array to splice. (Required)
 * @param index 	 Index at which to start changing the array. If negative, will begin that many elements from the end. (Required)
 * @param howMany 	 An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element. If no howMany parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after index are removed. (Required)
 * @return The updated array. 
 * @author Joshua Miller (joshuamil@gmail.com) 
 * @version 1, July 24, 2012 
 */
function arraySplice(array, index, howMany) {
	var i = 0;
	
	// If negative, will begin that many elements from the end	
	if (index <= 0){
		index = arrayLen(array) + (index + 1);
	}

	// get rid of however many they specify
	for (i=1; i LE howMany; i++){
		if (index LE arrayLen(array)){
			arrayDeleteAt(array, index);
		}
	}

	for (i=4; i LE arrayLen(arguments); i++){
		if (index GE arrayLen(array)){
			arrayAppend(array, arguments[i]);
			index++;
		}else{
			arrayInsertAt(array, index+(i-4), arguments[i]);
		}
	}

	return array;
}
blog comments powered by Disqus

Search CFLib.org


Latest Additions

Kevin Cotton added
date2ExcelDate
May 5, 2016

Raymond Camden added
CapFirst
April 25, 2016

Chris Wigginton added
loremIpsum
January 18, 2016

Gary Stanton added
calculateArrival...
November 19, 2015

Sebastiaan Naafs - van Dijk added
getDaysInQuarter
November 13, 2015

Created by Raymond Camden / Design by Justin Johnson