/********************************************************************
                        JavaScript Libraries 
 
                      Copyright 2005, Demachina 
                          www.demachina.com 
 
                        All rights reserved 
             
                  Document author: Jeroen Ritmeijer 
 
 FILENAME      : StringBuilder.js
 PURPOSE       : Fast stringbuilder class that makes it feasible to
				 perform large amounts of string concatenations. 
				 This is very similar to Java's StringBuffer and
				 .NET's StringBuilder with similar advantages
 MODULE        : Libraries
 DEPENDENCIES  : -

 TO-DO         : -
 KNOWN ISSUES  : -
 TAB SIZE      : 4
 HISTORY       : -
'*******************************************************************/


/********************************************************************
 FUNCTION  : CStringBuilder 
 PURPOSE   : Constructor for the object. 
 ASSUMES   : -
 AFFECTS   : -
 PARAMETERS: initialValue
 RETURNS   : A fully constructed object.
********************************************************************/
function CStringBuilder(initialValue)
{
	///////////////////// Method definitions ////////////////////////
	this.append			= CStringBuilder_Append;
	this.clear			= CStringBuilder_Clear;
	this.length			= CStringBuilder_Length;
	this.toString		= CStringBuilder_ToString;

	//////////////////// Property definitions ///////////////////////
	this.buffer			= new Array();
	this.bufferLength	= 0;
	
	////////////////////// Constructor code ////////////////////////
	if(initialValue != null)
		this.append(initialValue);
}


/********************************************************************
 FUNCTION  : CStringBuilder_Append
 PURPOSE   : Append a string to the internal buffer.
 ASSUMES   : -
 AFFECTS   : -
 PARAMETERS: appendValue - the string to add to the buffer.
 RETURNS   : -
********************************************************************/
function CStringBuilder_Append(appendValue)
{
	// ** validate data
	if(appendValue == null)
	{
		return;
	}
	
	// ** Increase the internal bufferlength
	this.bufferLength += appendValue.length;
	
	// ** And add the new value to the array.
	this.buffer.push(appendValue)
}


/********************************************************************
 FUNCTION  : CStringBuilder_Clear
 PURPOSE   : Clear the entire buffer
 ASSUMES   : -
 AFFECTS   : -
 PARAMETERS: -
 RETURNS   : -
********************************************************************/
function CStringBuilder_Clear()
{
	this.buffer = new Array();
	this.bufferLength = 0;
}


/********************************************************************
 FUNCTION  : CStringBuilder_Length
 PURPOSE   : Return the length of the text in the buffer
 ASSUMES   : -
 AFFECTS   : -
 PARAMETERS: -
 RETURNS   : The length of the text in the buffer
********************************************************************/
function CStringBuilder_Length()
{
	return this.bufferLength;
}


/********************************************************************
 FUNCTION  : CStringBuilder_ToString
 PURPOSE   : Return the text in the buffer
 ASSUMES   : -
 AFFECTS   : -
 PARAMETERS: -
 RETURNS   : A string containing the entire buffer contents
********************************************************************/
function CStringBuilder_ToString()
{
	// ** concatenate the contents of the array together into a single string
	return this.buffer.join("");
}