String Object, written in 2010

string.php

<?php

// String Object
// Copyright (c) 2010 Kijin Sung <kijin@kijinsung.com>
// License: WTFPL <http://www.wtfpl.net/>

class String
{
    // Some properties.
    
    protected $value;
    protected $encoding;
    
    // Constructor.
    
    public function __construct($value, $encoding = 'UTF-8')
    {
        // Check the encoding.
        
        if (!in_array($encoding, mb_list_encodings()))
        {
            throw new StringEncodingException('Invalid encoding: ' . $encoding);
        }
        
        // Check the string against the encoding.
        
        if (!mb_check_encoding($value, $encoding))
        {
            throw new StringEncodingException('Provided string is not valid ' . $encoding);
        }
        
        // Save to instance.
        
        $this->value = (string)$value;
        $this->encoding = (string)$encoding;
    }
    
    // Cast to string.
    
    public function __toString()
    {
        // Return the current value.
        
        return $this->value;
    }
    
    // Generic getter function.
    
    public function __get($name)
    {
        // This function handles several simple properties.
        
        switch ($name)
        {
            // Value.
            
            case 'value':
                return $this->value;
                
            // Encoding.
            
            case 'encoding':
                return $this->encoding;
            
            // Length (in characters).
            
            case 'length':
            case 'len':
                return mb_strlen($this->value, $this->encoding);
            
            // Length (in bytes).
            
            case 'bytelength':
            case 'bytelen':
                return strlen($this->value);
            
            // Nonexistent properties.
            
            default: throw new StringException('Property does not exist: ' . $name);
        }
    }
    
    // Generic setter function.
    
    public function __set($name, $value)
    {
        // This function handles several simple properties.
        
        switch ($name)
        {
            // Setting a new value.
            
            case 'value':
                
                // Check the string against the encoding.
                
                if (!mb_check_encoding($value, $this->encoding))
                {
                    throw new StringEncodingException('Provided string is not valid ' . $encoding);
                }
                
                // Save to instance.
                
                $this->value = (string)$value;
                return;
            
            // Nonexistent properties.
            
            default: throw new StringException('Property does not exist: ' . $name);
        }
    }
    
    // Set a new encoding.
    
    public function setEncoding($encoding)
    {
        // Check the encoding.
        
        if (!in_array($encoding, mb_list_encodings()))
        {
            throw new StringEncodingException('Invalid encoding: ' . $encoding);
        }
        
        // Convert and save.
        
        $this->value = mb_convert_encoding($this->value, $encoding, $this->encoding);
        $this->encoding = (string)$encoding;
    }
    
    // Search and match methods.
    
    public function match($regex)
    {
        return (bool)preg_match($regex, $this->value);
    }
    
    public function startsWith($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return strncmp($this->value, $str, strlen($str)) ? false : true;
        }
        else
        {
            return strncasecmp($this->value, $str, strlen($str)) ? false : true;
        }
    }
    
    public function endsWith($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return strncmp(strrev($this->value), strrev($str), strlen($str)) ? false : true;
        }
        else
        {
            return strncasecmp(strrev($this->value), strrev($str), strlen($str)) ? false : true;
        }
    }
    
    public function compare($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return strcmp($this->value, $str);
        }
        else
        {
            return strcasecmp($this->value, $str);
        }
    }
    
    public function contains($str, $case_sensitive = true)
    {
        return (bool)$this->find($str, $case_sensitive);
    }
    
    public function findFirst($str, $case_sensitive = true)
    {
        return $this->find($str, $case_sensitive);
    }
    
    public function find($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return mb_strpos($this->value, $str, $this->encoding);
        }
        else
        {
            return mb_stripos($this->value, $str, $this->encoding);
        }
    }
    
    public function findLast($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return mb_strrpos($this->value, $str, $this->encoding);
        }
        else
        {
            return mb_strripos($this->value, $str, $this->encoding);
        }
    }
    
    // Substring methods.
    
    public function getChar($position)
    {
        return new String(mb_substr($this->value, $position, 1, $this->encoding), $this->encoding);
    }
    
    public function substr($start, $end = false)
    {
        if ($end === false)
        {
            return new String(mb_substr($this->value, $position, mb_strlen($this->value, $this->encoding) - $position,
                              $this->encoding), $this->encoding);
        }
        else
        {
            return new String(mb_substr($this->value, $position, $end, $this->encoding), $this->encoding);
        }
    }
    
    // Basic transformation methods.
    
    public function trim($charlist = " \0\r\n\t\x0B")
    {
        return new String(trim($this->value, $charlist), $this->encoding);
    }
    
    public function trimLeft($charlist = " \0\r\n\t\x0B")
    {
        return new String(ltrim($this->value, $charlist), $this->encoding);
    }
    
    public function trimRight($charlist = " \0\r\n\t\x0B")
    {
        return new String(rtrim($this->value, $charlist), $this->encoding);
    }
    
    public function padLeft($length, $char = ' ')
    {
        return new String(str_pad($this->value, $length, $char, STR_PAD_LEFT), $this->encoding);
    }
    
    public function padRight($length, $char = ' ')
    {
        return new String(str_pad($this->value, $length, $char, STR_PAD_RIGHT), $this->encoding);
    }
    
    public function toLower()
    {
        return new String(mb_strtolower($this->value, $this->encoding), $this->encoding);
    }
    
    public function toUpper()
    {
        return new String(mb_strtoupper($this->value, $this->encoding), $this->encoding);
    }
    
    // Major modification methods.
    
    public function append($str)
    {
        return new String($this->value . $str, $this->encoding);
    }
    
    public function prepend($str)
    {
        return new String($str . $this->value, $this->encoding);
    }
    
    public function insert($str, $position)
    {
        return new String(mb_substr($this->value, 0, $position, $this->encoding) . $str .
                          mb_substr($this->value, $position, mb_strlen($this->value, $this->encoding) - $position, $this->encoding),
                          $this->encoding);
    }
    
    public function replace($str1, $str2, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return new String(str_replace($str1, $str2, $this->value), $this->encoding);
        }
        else
        {
            return new String(str_ireplace($str1, $str2, $this->value), $this->encoding);
        }
    }
    
    public function remove($str, $case_sensitive = true)
    {
        if ($case_sensitive)
        {
            return new String(str_replace($str1, '', $this->value), $this->encoding);
        }
        else
        {
            return new String(str_ireplace($str1, '', $this->value), $this->encoding);
        }
    }
    
    // Splitting methods.
    
    public function split($delimiter = ' ', $limit = false)
    {
        $exploded = $limit ? explode($delimiter, $this->value, $limit) : explode($delimiter, $this->value);
        $return = array();
        foreach ($exploded as $item)
        {
            $return[] = new String($item, $this->encoding);
        }
        return $return;
    }
    
    // Escaping methods.
    
    public function escape($double_encode = true)
    {
        return new String(htmlentities($this->value, ENT_COMPAT, $this->encoding, $double_encode), $this->encoding);
    }
    
    public function unescape()
    {
        return new String(html_entity_decode($this->value, ENT_COMPAT, $this->encoding), $this->encoding);
    }
    
    public function urlencode()
    {
        return new String(urlencode($this->value), $this->encoding);
    }
    
    public function urldecode()
    {
        return new String(urldecode($this->value), $this->encoding);
    }
    
    public function stripTags($allowed = '')
    {
        return new String(strip_tags($this->value, $allowed), $this->encoding);
    }
    
    // Hash, 7-bit encoding, and checksum methods.
    
    public function uuencode()
    {
        return new String(convert_uuencode($this->value), $this->encoding);
    }
    
    public function base64()
    {
        return new String(base64_encode($this->value), $this->encoding);
    }
    
    public function md5($raw_output = false)
    {
        return new String(md5($this->value, $raw_output), $this->encoding);
    }
    
    public function sha1($raw_output = false)
    {
        return new String(sha1($this->value, $raw_output), $this->encoding);
    }
    
    public function hash($algorithm, $raw_output = false)
    {
        return new String(hash($algorithm, $this->value, $raw_output), $this->encoding);
    }
    
    public function crc32()
    {
        return crc32($this->value);
    }
}

// Exceptions.

class StringException extends Exception { }
class StringEncodingException extends StringException { }