// ===========================================================================
// 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 stringArrayInsertAtIndex>
//<owner "Internal">
//
//<synopsis>
//		int stringArrayInsertAtIndex(int $index, string[] $list, string $item)
//
//<description>
//		Insert $item at $index in the string 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 $str at
//		string[] $list   A list of string values.
//		string   $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
//  string $list[] = {"item1", "item3"};
//  // Result: item1 item3 //
//  // Insert in the middle of the sequence
//  stringArrayInsertAtIndex(1, $list, "item2");
//  // Result: 1 //
//  print $list;
//  // Result: item1 item2 item3 //
//  // Insert before the first element
//  stringArrayInsertAtIndex(-1, $list, "item4" );
//  // Result: 0 //
//  // Insert at (or after) the end of the sequence
//  stringArrayInsertAtIndex( 10, $list, "item4" );
//  // Result: 1 //
//  print $list;
//  // Result: item1 item2 item3 item4 //
//  // Insert at the beginning of the sequence
//  stringArrayInsertAtIndex( 0, $list, "item0" );
//  // Result: 1 //
//  print $list;
//  // Result: item0 item1 item2 item3 item4 //
//
//
//</doc>
//

global proc int stringArrayInsertAtIndex( int $index, string $list[], string $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;
}