File: documentation.txt

************************Class Description************************
A simple class that allows the extensive manipulation of
a string.
The class is loosely based on the java StringBuffer class!

The class also has some 'enumeration' functions to enable
easy scanning operation over the string.

The functions will not accept out of range requests. So no error will occur within the code,
 However
no warning is given when an out of range request is provided. So therefore the
onus is on the user of this class to supply correct parameters

This class has not been fully tested,
though it has been used in a commercial application for sometime.
It was written in June 2004 under PHP v4

*****************************************************************

 ***KNOW ISSUES******************************************
 Avoid using a backward iteration whilst deleting,
 as I would expect this to cause problems in some cases!
 ********************************************************

*********************Contact and Bug report***********************
 ----David Johns www.javaservices.co.uk ---
 --- open source page http://www.javaservices.co.uk/example.htm?p=9
 ----e-mail saltash5@nildram.co.uk ---------

********************Licence****************************************
This software is covered by The GNU General Public License (GPL)
Author David Johns
Version 1.0
Date December 2004

*****************************************************************



********************Constructor***********************
 
 constructor (string) sets the string
 
 
 ****************General functions********************
 
 buflen() returns the length of the string
 
 
 delete_char_at($int) removes the char' at the specified position, returns the string
 
 
 to_string() returns the string
 


 get_current_pos() returns the current position of the pointer used for iteration


insert($int,$string) allows insertion of a string at a given point
within a string.
It also allows a string to be placed on the -
end of the current string.




get_char_at($int) returns the char at the position specified



get_current_char() returns the current char as dictated by the pointer




 set_char_at($int,$chr) returns the current string after a char has been appended The position must be valid -
however adding a char to the end of the string is allowed.

reset_buffer($string) resets the buffer to allow new string to be created
 best to create a new instance! 

****************************************************************************




***********Enumaration EXAMPLE************************************************

To move through a string and retrieve each character simply use

			 while($buffer->has_more()){
              			echo $buffer->get_next_char();
				}

used to simplify iteration
no need to test or know the size of the string

The internal pointer will stop at the end of the string

To get back to the start of the string use

$buffer->pointer_reset()

or move back through the string again the pointer will stop automatically

			while($buffer->has_less()){
         			echo $buffer->get_prev_char();
         			}

**************************************************************************

 ******Enumeration functions************************************* 

 
 
*************************************** 
forward iteration is safe
 
backward may cause problems if
a char is deleted ahead of the pointer
***************************************

 


 get_next_char() iterates in +ve direction through the string
returns the char at that position.
The first time this function is called it returns
the first char, the the second.








get_prev_char()iterates in -ve direction through the string
returns the char at that position.
The first time this function is called it returns
the first char, then the second from the cursor postion.




has_more()Enumeration
returns true if within the bounderies of the string
use- while(this->buffer->has_more){} for +ve iteration


 has_less()Enumeration
returns true if within the bounderies of the string
use- while(this->buffer){} for -ve iteration


 
 
 function pointer_reset()
 used to place the pointer at the start of the string
 
 
***********************************************************************