// Copyright (C) 2007 Cognos Incorporated. All Rights Reserved.
// Cognos and the Cognos logo are trademarks of Cognos Incorporated.

//
// This class implement a generic Dictionary data structure. 
//

var DICTIONARY_INVALID_KEY = -1;
var DICTIONARY_SUCCESS = 1;

/*
	Constructor

	Parameters:

	Returns:
*/
function CDictionary()
{
	// CDictionary uses an array to store key/value pairs.
	this.m_aValues = new Array();
}

/*
	Adds a key/value pair in the dictionary.
	If the key was used before, its value will be overwrite.

	Parameters:
		key (string) - The key to look for in the dictionary.
		value (object) - The value associated to the key

	Returns:
*/
function CDictionary_add(sKey, oValue)
{
	if (typeof sKey != "string" && typeof sKey != "number")
	{
		return DICTIONARY_INVALID_KEY;
	}
	this.m_aValues[sKey] = oValue;
	return DICTIONARY_SUCCESS;
}

/*
	Returns true if the keys is already used.

	Parameters:
		key (string) - The key to look for in the dictionary.

	Returns:
		a boolean.
*/
function CDictionary_exists(sKey)
{
	if (typeof sKey != "string" && typeof sKey != "number")
	{
		return false;
	}
	return (typeof this.m_aValues[sKey] != "undefined");
}

/*
	Returns the associated to a key in the dictionary.
	Returns null if the key doesn't exists.

	Parameters:
		key (string) - the key to look for

	Returns:
		an object, associated to the key.
*/
function CDictionary_get(sKey)
{
	if (typeof sKey != "string" && typeof sKey != "number")
	{
		return null;
	}
	if (this.exists(sKey) === true)
	{
		return this.m_aValues[sKey];
	}
	else
	{
		return null;
	}
}

/*
	Returns all keys used in this dictionary. Ordered alphabetically.
	Returns an empty array if the dictionary is empty.

	Parameters:

	Returns:
		a sorted array of strings.
*/
function CDictionary_keys()
{
	var aKeys = new Array();
	for (var idxValue in this.m_aValues)
	{
		aKeys.push(idxValue);
	}
	
	return aKeys.sort();
}

/*
	Remove a key/value pair from this dictionary. 

	Parameters:
		key (string) to remove from the dictionary.
	
	Returns:
		Returns the object removed. Null if the key didn't exists.
*/
function CDictionary_remove(sKey)
{
	if (typeof sKey != "string" && typeof sKey != "number")
	{
		return DICTIONARY_INVALID_KEY;
	}
	var oRetVal = null;
	
	// build a new array with all the value except the one to remove.
	var aNewArr = new Array();
	
	for (var idxValue in this.m_aValues) 
	{
		if (idxValue == sKey)
		{
			// key matched. Remove this value by not adding it to the new array...
			// Keep the value (to be returned).
			oRetVal = this.m_aValues[idxValue];
		}
		else
		{
			// key didn't match. Add the key/value pair to the new array
			aNewArr[idxValue] = this.m_aValues[idxValue];
		}
	}
	
	// Update the private array.
	this.m_aValues = aNewArr;
	
	return oRetVal;
}

/*
	Removes all key/value pairs from this dictionary. 

	Parameters:

	Returns:
*/
function CDictionary_removeAll()
{
	this.m_aValues = new Array();
	return DICTIONARY_SUCCESS;
}


// Add functions to the CDictionary class
CDictionary.prototype.add = CDictionary_add;
CDictionary.prototype.exists = CDictionary_exists;
CDictionary.prototype.get = CDictionary_get;
CDictionary.prototype.keys = CDictionary_keys;
CDictionary.prototype.remove = CDictionary_remove;
CDictionary.prototype.removeAll = CDictionary_removeAll;