/**
 * This file must be included to add functionality to strings.
 * 
 * @version 2010-11-23
 * @author <a href="mailto:r.tennapel@griponservice.nl?SUBJECT=string.js">R. ten Napel, ing.</a>
 **/

/**
 * Returns if a string contains a particular string.
 * 
 * @param String		The string to search for.
 * 
 * @return				True or false.
 **/
String.prototype.contains = function(string) {
	return (this.indexOf(string) != -1);
};

/**
 * Returns if a string starts with a particular string.
 * 
 * @param string		The string to check.
 * 
 * @return				True or false.
 **/
String.prototype.startsWith = function(string) {
	return this.indexOf(string) == 0;
};

/**
 * Returns if a string ends with a particular string.
 * 
 * @param string		The string to check.
 * 
 * @return				True or false.
 **/
String.prototype.endsWith = function(string) {
	return this.substring(this.length - string.length, this.length) == string;
};

/**
 * Replace all occurences of 'find' and replace it with 'replace'.
 * 
 * @param find			The string to find.
 * @param replace		The replacement.
 * 
 * @return				The changed string.
 **/
String.prototype.replaceAll = function(find, replace) {
	return this.replace(new RegExp(find, "gi"), replace);
};

/**
 * Return the URL-encoded version of this string. Replace all '+'-signs (with %2B) and linebreaks (with %0A).
 * 
 * @return				The URL-encoded string.
 **/
String.prototype.escape = function() {
	return escape(this).replace("+", "%2B").replaceAll("\n", "%0A");
};

/**
 * Removes whitespace at the start of a string.
 * 
 * @return				The trimmed string.
 **/
String.prototype.ltrim = function() {
	return this.replace(/^\s+/, "");
};

/**
 * Removes whitespace at the end of a string.
 * 
 * @return				The trimmed string.
 **/
String.prototype.rtrim = function() {
	return this.replace(/\s+$/, "");
};

/**
 * Removes whitespace at the start & end of a string.
 * 
 * @return				The trimmed string.
 **/
String.prototype.trim = function() {
	return this.ltrim().rtrim();
};

/**
 * Pad the string to a certain length with a certain character.
 * 
 * @param length		The length of the padded string (-x for padding before or x for padding after).
 * @param character		The character to pad the string with.
 * 
 * @return				The padded string.
 **/
String.prototype.pad = function(length, character) {
	var loop = (length < 0) ? -length : length;
	
	// Check if padding is necessery:
	if (loop - this.length <= 0) {
		return this;
	}
	
	// Do the padding:
	var pad = "";
	for (var i = 0; i < loop - this.length; i++) {
		pad += character;
	}
	
	// Return string with padding:
	if (length > 0) {
		return this + pad;
	}
	
	return pad + this;
};

/**
 * Explodes a string into a maximum number of chunks. This function is the same as string.prototype.split except that all the
 * parts that exceed "chunks" are added to the last chunk.
 * 
 * @param separator		The separator string.
 * @param chunks		The maximum number of chunks (all exceeding will be added to the last chunk).
 * 
 * @return				An array with chunks.
 **/
String.prototype.explode = function(separator, chunks) {
	// If only 1 chunk, return the complete string:
	if (chunks <= 1) {
		return this;
	}
	
	// Split the string:
	var parts = this.split(separator);
	
	// When chunks is not defined, or in range, return all parts:
	if (chunks == null || parts.length <= chunks) {
		return parts;
	}
	
	// Append all parts > chunks to the last allowed part:
	var loop = parts.length - chunks;
	for (var i = 0; i < loop; i++) {
		parts[parts.length - 2] += separator + parts.pop();
	}
	
	return parts;
};

/**
 * Convert an URL-string with keys & values to an object.
 * 
 * @return				An object with all the key-value-pairs.
 **/
String.prototype.url2obj = function() {
	var string = this;
	
	// If "?" detected, remove everything before it:
	var pos = string.indexOf("?");
	if (pos != -1) { string = string.substring(pos + 1); }
	
	// Split all pairs:
	var pairs = string.split("&");
	
	// Create empty object:
	var obj = {};
	
	// Add all parameters:
	for (var p = 0; p < pairs.length; p++) {
		pairs[p] = pairs[p].explode("=", 2);
		obj[pairs[p][0]] = pairs[p][1];
	}
	
	return obj;
};

/**
 * Remove all HTML-comments from the string.
 * 
 * @see					<a href="http://htmlhelp.com/reference/wilbur/misc/comment.html">HTML comments</a>
 * 
 * @return				The original text without HTML-comments.
 **/
String.prototype.stripComments = function() {
	return this.replace(/<!(--.*--)?>/g, "");
};

/**
 * Remove all (given) HTML-entities (and comments).
 * 
 * @param entities		An array with entities that are (not) allowed.
 * @param allowed		If the given entities are allowed or not.
 * 
 * @return				The original text without HTML-tags.
 **/
String.prototype.stripHTML = function(entities, allowed) {
	// Strip all comments:
	var string = this.stripComments();
	
	// Strip all HTML-entities:
	if (arguments.length == 0) {
		string = string.replace(/<\/?(?!\!)[^>]*>/gi, "");
	// Strip all but given HTML-entities:
	} else if (allowed) {
		var regExp = "<\/?(?!(" + entities.join("|") + ")\\b)\\b[^>]*>";
		string = string.replace(new RegExp(regExp, "gi"), "");
	// Strip all given HTML-entities:
	} else {
		var regExp = "<\/?(" + entities.join("|") + ")(\\s+[^>]*)?>";
		string = string.replace(new RegExp(regExp, "gi"), "");
	}
	
	return string;
};

/**
 * Alternate notation for the $-function. Use it like "elemId".$(). If the $-function doesn't exist, an alert will be generated.
 * 
 * @return				The element that has the given string as ID.
 **/
String.prototype.$ = function() {
	try {
		return $(String(this));
	} catch(e) {
		alert(e.message);
	}
	
	return null;
};