/**
 * @fileoverview (GENERIC) Provides generic keyed data (strings) functionality.
 */

/** 
 * @class (GENERIC) Provides generic keyed data (strings) functionality.
 * <p>
 * <b>Component:</b> Generic<br>
 * <b>Type:</b> Object
 * <p>
 * <b>Functionality:</b>
 * <p>
 * Allows strings to be used to store multiple information segments (c.f. 
 * the browser query string).
 * <p>
 * <b>Notes:</b>
 * <p>
 * The default delimeter used by the object is ';;'.
 */
var _kd = {

	// ******************************************************************
	// Methods.
	// ******************************************************************

	/**
	 * Gets the value of a keyed data item from the source string.
	 * 
	 * @param	{string}	key				The name of the keyed item to get.
	 * @param	{string}	source			The source string to grab the keyed item from.
	 * @param	{string}	default_value	The (optional) default value to return if the keyed item is not found - default null.
	 * @param	{string}	delimeter		The (optional) delimeter to use when searching the source string - default ;;.
	 * @return	{stromng}					The value of the keyed item.
	 */
	get: function (key, source, default_value, delimeter) {

		// Check the parameters.
		if (key == null || key == '') return;
		if (source == null) var source = '';
		if (delimeter == null) var delimeter = ';;';

		// Delimeter length;
		var del_length = delimeter.length;
		
		// Get the start of any existant key.
		var start = source.indexOf(delimeter+key+'=');

		// Return default if the key doesn't exist.
		if (start == -1) return default_value;

		// Otherwise get the substring.
		
		// End position (or end of string).
		var end = source.indexOf(delimeter, start + del_length);
		if (end == -1) end = source.length;
		
		// Return the value only.
		return source.substring(start + key.length + del_length + 1, end);
	},

	/**
	 * Sets the value of a keyed data item in the source string.
	 * 
	 * @param	{string}	key				The name of the keyed item to get.
	 * @param	{string}	value			The value to set the keyed item to.
	 * @param	{string}	source			The source string to insert the keyed item into.
	 * @param	{string}	delimeter		The (optional) delimeter to use when searching the source string - default ;;.
	 * @return	{string}					The updated source string value.
	 */
	set: function (key, value, source, delimeter) {

		// Check the parameters.
		if (key == null || key == '' || source == null) return;
		if (value == null) var value = '';
		if (delimeter == null) var delimeter = ';;';

		// Delimeter length;
		var del_length = delimeter.length;

		// Get the start of any existant key.
		var start = source.indexOf(delimeter+key+'=');

		// Doesn't excist so append and exit.
		if (start == -1) {
			
			// Append delimeter if required.
			if ((source.length > del_length && source.substr(source.length - del_length) != delimeter) || source.length == 0) source += delimeter;
			
			// Append the value.
			source += key+'='+value+delimeter;

			// Return  the updated value.
			return source;
		}

		// Does exist so replace the value.

		// End position (or end of string).
		var end = source.indexOf(delimeter, start + del_length);
		if (end == -1) end = source.length;

		// Return the recreated string.
		return source.substring(0, start) + delimeter+key+'='+value + source.substring(end, source.length);
	},
	
	/**
	 * Deletes a keyed data item from the source string.
	 * 
	 * @param	{string}	key				The name of the keyed item to delete.
	 * @param	{string}	source			The source string to delete the keyed item from.
	 * @param	{string}	delimeter		The (optional) delimeter to use when searching the source string - default ;;.
	 * @return	{string}					The updated source string value.
	 */
	del: function (key, source, delimeter) {

		// Check the parameters.
		if (key == null || key == '' || source == null) return;
		if (delimeter == null) var delimeter = ';;';

		// Delimeter length;
		var del_length = delimeter.length;

		// Get the start of any existant key.
		var start = source.indexOf(delimeter+key+'=');

		// Doesn't excist so exit.
		if (start == -1) return source;

		// Does exist so replace the value.

		// End position (or end of string).
		var end = source.indexOf(delimeter, start + del_length);
		if (end == -1) end = source.length;

		// Return the recreated string.
		return source.substring(0, start) + source.substring(end, source.length);
	}
}