// ===========================================================================
// Copyright 2018 Autodesk, Inc. All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk license
// agreement provided at the time of installation or download, or which
// otherwise accompanies this software in either electronic or hard copy form.
// ===========================================================================
//
//<doc>
//<name intArrayInsertAtIndex>
//
//<synopsis>
//		int intArrayInsertAtIndex(int $index, int[] $list, int $item)
//
//<description>
//		Insert $item at $index in the integer array $list. If $index is
//		greater than the last index of $list, $item will be placed at the
//		end of the list.
//
//<flags>
//		int   $index  The index into $list to add $item at
//		int[] $list   A list of int values.
//		int   $item   The new item to add to $list at $index
//
//<returns>
//		int : Returns false if $index was negative and true on
//			  success.
//
//<examples>
//  // Initialize the list
//  int $list[] = {1, 3};
//  // Result: 1 3 //
//  // Insert in the middle of the sequence
//  intArrayInsertAtIndex(1, $list, 2 );
//  // Result: 1 //
//  print $list;
//  // Result: 1 2 3 //
//  // Insert before the first element
//  intArrayInsertAtIndex(-1, $list, 4 );
//  // Result: 0 //
//  // Insert at ( or after ) the last element
//  intArrayInsertAtIndex(10, $list, 4 );
//  // Result: 1 //
//  print $list;
//  // Result: 1 2 3 4 //
//  // Insert at the beginning of the sequence
//  intArrayInsertAtIndex( 0, $list, 0 );
//  // Result: 1 //
//  print $list;
//  // Result: 0 1 2 3 4 //
//
//</doc>
//

global proc int intArrayInsertAtIndex( int $index, int $list[], int $item )
{
	int $len = size( $list );

	// Check for a invalid indeces ...
	//
	if ( $index < 0 )
		return false;

	// ... or for the simple case of appending to the 
	//     end of the array
	//
	if ( $index >= $len )
	{
		$list[$len] = $item;
		return true;
	}

	// If either of these tests fail, we are inserting 
	// somewhere into the middle of the list
	
	// First do an in-place copy of all entries after $index
	//
	int $i;
	for ($i = $len-1; $i >= $index; $i--)
		$list[$i+1] = $list[$i];

	// Lastly copy entry at $index
	//
	$list[$index] = $item;

	return true;
}