STRINGBUILDER / STRINGBUFFER EN PHP (CLASSE SPÉCIALEMENT CONÇUE POUR MANIPULER DES CHAÎNES DE CARACTÈRES...)

<?php
/**
 * StringBuilder.class.php
 * 
 * Une simple classe qui permet une manipulation étendue des String
 * Cette classe est basé sur la classe StringBuider de Java.
 * StringBuilder a été codé pour PHP5, elle ne fonctionnera en aucun cas des versions inférieur à celle-ci.
 * 
 * Cette classe n'est pas destiné à être hérité
 * 
 * Created on 9 August. 07
 * 
 * @author Donald_Duck
 * @version 1.0
 * 
 * @todo Liste des méthodes a effectuées: 	->ensureCapacity
 * 						->getChars
 * 						->offsetByCodePoints
 */
class StringBuilder {

	/**
	 * @desc Tableau contenant les strings
	 */
	private $buffer;
	
	/**
	 * @desc Constructeur de la classe
	 * @param String $string String a concaténer
	 * @return void
	 * @since 1.0 - 9 août 07
	 * @access public
	 */
	public function __construct($str="") {
		$this->buffer = str_split($str);
	}
	
	/**
	 * @desc Concatène le String passer en paramètre avec celui en mémoire
	 * @param String $str Le string a concaténer
	 * @return void
	 * @since 1.0 - 9 août 07
	 * @access public 
	 * @final
	 */
	public final function append($str) {
		$this->buffer = array_merge_recursive($this->buffer, str_split($str));
	}
	
	/**
	 * @desc Retourne la capacité courante
	 * @return int La capacity pour l'objet StringBuilder
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function capacity() {
		if (is_array($this->buffer) && !empty($this->buffer)) {
			return count($this->buffer);
		}
		return null;
	}
	
	/**
	 * @desc Retourne le caractère spécifié pour l'index demandé
	 * @param int $index La position du caractère a retourné
	 * @return Char Le caractère demandé
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 * @deprecated 1.0 - 9 août 07 Utilisé plutôt @see codePointAt()
	 */
	public final function charAt($index) {
		try {
			return $this->buffer[$index];
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
	}
	
	/**
	 * @desc Retourne le point de code unicode pour l'index spécifié
	 * @param int $index L'index du caractère dans le String
	 * @return int Le point de code unicode
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 * @deprecated 1.0 - 9 août 07 (PHP ne gère pas encore les points unicode)
	 */
	public final function codePointAt ($index) {
		//TODO
	}
	
	/**
	 * @desc Retourne le point de code unicode après l'index spécifié
	 * @param int $index L'index du caractère dans le String
	 * @return int Le point de code unicode
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 * @deprecated 1.0 - 9 août 07 (PHP ne gère pas encore les points unicode)
	 */
	public final function codePointBefore ($index) {
		//TODO
	}
	
	/**
	 * @desc Retourne le nombre de points de code unicode entre les index spécifiés
	 * @param int $beginIndex L'index de départ du caractère dans le String
	 * @param int $endIndex L'index de fin du caracère dans le String
	 * @return int Le point de code unicode
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 * @deprecated 1.0 - 9 août 07 (PHP ne gère pas encore les points unicode)
	 */
	public final function codePointCount ($beginIndex, $endIndex) {
		//TODO
	}
	
	/**
	 * @desc Supprime le caractère entre les deux index pour le String en mémoire
	 * @param int $start L'index de début
	 * @param int $end L'index de fin
	 * @return StringBuilder L'objet StringBuilder
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function delete($start, $end) {
		try {
			for ($start; $start < $end; $start++) {
				unset($this->buffer[$start]);
			}
			$this->buffer = array_values($this->buffer);
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
		
		return $this;
	}
	
	/**
	 * @desc Supprime le caractère pour une position spécifié dans la séquence
	 * @param int $index La position du caractèren à supprimé
	 * @return StringBuilder L'Objet StringBuilder
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function deleteCharAt($index) {
		try {
			unset($this->buffer[$index]);
			$this->buffer = array_values($this->buffer);
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
	
		return $this;
	}
	
	/**
	 * @desc Retourne l'index de la première occurrence de la sous-chaîne spécifiée.
	 * @param String $str Le string ou le char rechercher
	 * @param int $offset L'index ou commencer la recherche
	 * @return int $fromIndex L'index de la première occurence trouvé
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function indexOf($str, $fromIndex=0) {
		$string = implode('', $this->buffer);
		return strpos($string, $str, $fromIndex);
	}
	
	/**
	 * @desc Insere un String dans la sequence de caractère en cours
	 * @param int $offset La position a laquelle on veut insérer le String
	 * @param String $str Le string a insérer
	 * @return StringBuilder Le StringBuilder
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function insert($offset, $str){
		$string = implode('', $this->buffer);
		
		try {
			$leftPart= substr($string, 0, $offset);
			$rightPart = substr($string, $offset, strlen($string));
			$string = $leftPart.$str.$rightPart;
			$this->buffer = str_split($string);
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
		
		return $this;
	}
	
	/**
	 * @desc Retourne l'index du dernier caractère trouvé pour la chaine (ou le caractère) recherchée
	 * @param String $str La chaine recherchée
	 * @param int $fromIndex L'index ou commencer la recherche
	 * @return int L'index a l'extreme droite de la chaine recherchée
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function lastIndexOf($str, $fromIndex) {
		$string = implode('', $this->buffer);
		$pos = strpos($string, $str, $fromIndex);
		if ($pos !== false) {
			return $pos + strlen($str);
		}
		
		return false;
	}
	
	/**
	 * @desc Retourne la longueur du string en mémoire
	 * @return int La longueur du string en mémoire
	 * @since 1.0 - 5 août 07
	 * @access public
	 * @final
	 */
	public final function length() {
		return strlen(implode('', $this->buffer));
	}
	
	/**
	 * @desc Remplace la chaine de caractère situé dans l'encadrement par celle passée en argument
	 * @param int $start L'index du début
	 * @param int $end L'index de fin
	 * @param String $str La chaine de caractère pour le remplacement
	 * @return StringBuilder Le StringBuilder
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function replace($start, $end, $str) {
		$string = implode('', $this->buffer);
		
		try {
			$this->buffer = array_splice($this->buffer, $start, $end-$start, str_split($str));
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
		
		return $this;
	}
	
	/**
	 * @desc Inverse l'ordre de sequence de la chaine de caractère en mémoire
	 * @return StringBuilder Le StringBuilder inversé
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function reverse() {
		$this->buffer = array_reverse($this->buffer);
	}
	
	/**
	 * @desc Remplace le caractère spécifié pour l'index par celui passé en argument
	 * @param int $index L'index pour le caractère du String en mémoire
	 * @param Char $ch Le caractère a remplacer
	 * @return void
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function setCharAt($index, $ch) {
		try {
			$this->buffer[$index] = $ch;
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
	}
	
	/**
	 * @desc Modifie la taille (en char) de la chaine de caractère en mémoire
	 * Si la taille indiquée est supérieur a celle en mémoire alors la taille en mémoire sera conservée
	 * @param int $newLength La nouvelle taille à affecter
	 * @return void
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function setLength($newLength) {
		$length = strlen(implode('', $this->buffer));
		if ($newLength < $length) {
			$string = substr(implode('', $this->buffer), 0, $newLength);
		}
	}
	
	/**
	 * @desc Retourne la séquence de caractère entre l'intervalle et construit un nouveau String builder avec
	 * @param int $start L'index du début
	 * @param int $end L'index de fin
	 * @return StringBuilder Le StringBuilder avec la chaine de caractère demandé en paramètre constructeur
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function subSequence($start, $end) {
		try {
			 return new StringBuilder(implode('', array_slice($this->buffer, $start, $end-$start)));
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
	}
	
	/**
	 * @desc Retourne un String contenant la sequence entre les intervalle
	 * @param int $start L'index du début
	 * @param int $end L'index de fin
	 * @return String Le String demandé
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function substring($start, $end=null) {
		if ($end === null) {
			$end = strlen(implode('', $this->buffer));
		}
		try {
			return implode('', array_slice($this->buffer, $start, $end-$start));
		} catch (Exception $e) {
			echo 	'Warning: ' , $e->getMessage(), 
					'Code: ' . $e->getCode(), 'Une erreur est survenue dans ',
					'Fichier: ' . $e->getFile(),
					'Ligne: ' . $e->getLine();
		}
	}
	
	/**
	 * @desc Convertit le tableau de String en un unique String
	 * @return String le String en mémoire
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function toString() {
		if (!empty($this->buffer)) {
			return implode('', $this->buffer);
		} else {
			return null;
		}
	}
	
	/**
	 * @desc Retourne la position courante du pointeur
	 * @return int La position du pointeur
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getCurrentPos(){
		return key($this->buffer);
	}
	
	/**
	 * @desc Retourne le caractère correspondant a la position courante du pointer
	 * @return Char Le caractère pointé
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getCurrentChar() {
		return current($this->buffer);
	}

	/**
	 * @desc Retourne le caractère précédant le caractère pointé par le pointeur
	 * @return Char Le caractère suivant
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getNextChar() {
		return next($this->buffer);
	}
	
	/**
	 * @desc Retourne le caractère succédant le caractère pointé par le pointeur
	 * @return Char Le caractère suivant
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getPrevChar() {
		return prev($this->buffer);
	}
	
	/**
	 * @desc Retourne le dernier caractère de la chaine de caractère en méméoire
	 * @return Char Le dernier caractère
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getEndChar() {
		return end($this->buffer);
	}
	
	/**
	 * @desc Retourne le premier caractère de la chaine de caractère en méméoire
	 * @return Char Le premier caractère
	 * @since 1.0 - 9 août 07
	 * @access public
	 * @final
	 */
	public final function getFirstChar() {
		reset($this->buffer);
		return current($this->buffer);
	}
	
	/**
	 * @desc Reinitialiser leStringBuilder pour lui affecter un nouveau String (= clean with $str)
	 * @param $String $str Le string de remplacement
	 * @return void
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function clean($str){
		$this->buffer = str_split($str);
	}

	/**
	 * @desc Remet le pointer a l'index 0
	 * @return void
	 * @since 1.0 - 10 août 07
	 * @access public
	 * @final
	 */
	public final function resetPointer(){
		reset($this->buffer);
	}
}
?>