1.4.0 release

CHANGELOG.md

@@ -1,3 +1,11 @@
+### 1.4.0 (2014-02-12)
+
+  * Implemented the IteratorAggregate interface, added chars()
+  * Renamed count() to countSubstr()
+  * Updated count() to implement Countable interface
+  * Implemented the ArrayAccess interface with positive and negative indices
+  * Switched from PSR-0 to PSR-4 autoloading
+
 ### 1.3.0 (2013-12-16)
 
   * Additional Bulgarian support for toAscii

README.md

@@ -1,17 +1,21 @@
 ![Stringy](http://danielstjules.com/stringy/logo.png)
 
-A PHP library with a variety of string manipulation functions with multibyte support. Offers both OO method chaining and a procedural-style static wrapper. Compatible with PHP 5.3+. Inspired by underscore.string.js.
+A PHP library with a variety of string manipulation functions with multibyte
+support. Offers both OO method chaining and a procedural-style static wrapper.
+Compatible with PHP 5.3+. Inspired by underscore.string.js.
 
 [![Build Status](https://travis-ci.org/danielstjules/Stringy.png)](https://travis-ci.org/danielstjules/Stringy)
 
 * [Requiring/Loading](#requiringloading)
 * [OO and Procedural](#oo-and-procedural)
+* [Implemented Interfaces](#implemented-interfaces)
 * [Methods](#methods)
     * [at](#at)
     * [camelize](#camelize)
+    * [chars](#chars)
     * [collapseWhitespace](#collapsewhitespace)
     * [contains](#contains)
-    * [count](#count)
+    * [countSubstr](#countsubstr)
     * [create](#create)
     * [dasherize](#dasherize)
     * [endsWith](#endswith)
@@ -84,9 +88,9 @@ require 'vendor/autoload.php';
 Otherwise, you can simply require the file directly:
 
 ```php
-require_once 'path/to/Stringy/src/Stringy/Stringy.php';
+require_once 'path/to/Stringy/src/Stringy.php';
 // or
-require_once 'path/to/Stringy/src/Stringy/StaticStringy.php';
+require_once 'path/to/Stringy/src/StaticStringy.php';
 ```
 
 And in either case, I'd suggest using an alias.
@@ -120,12 +124,50 @@ $string = S::collapseWhitespace('Fòô     Bàř', 'UTF-8');
 echo S::swapCase($string, 'UTF-8');  // 'fÒÔ bÀŘ'
 ```
 
+## Implemented Interfaces
+
+`Stringy\Stringy` implements the `IteratorAggregate` interface, meaning that
+`foreach` can be used with an instance of the class:
+
+``` php
+$stringy = S::create('Fòô Bàř', 'UTF-8');
+foreach ($stringy as $char) {
+    echo $char;
+}
+// 'Fòô Bàř'
+```
+
+It implements the `Countable` interface, enabling the use of `count()` to
+retrieve the number of characters in the string:
+
+``` php
+$stringy = S::create('Fòô', 'UTF-8');
+count($stringy);  // 3
+```
+
+Furthermore, the `ArrayAccess` interface has been implemented. As a result,
+`isset()` can be used to check if a character at a specific index exists. And
+since `Stringy\Stringy` is immutable, any call to `offsetSet` or `offsetUnset`
+will throw an exception. `offsetGet` has been implemented, however, and accepts
+both positive and negative indexes. Invalid indexes result in an
+`OutOfBoundsException`.
+
+``` php
+$stringy = S::create('Bàř', 'UTF-8');
+echo $stringy[2];     // 'ř'
+echo $stringy[-2];    // 'à'
+isset($stringy[-4]);  // false
+
+$stringy[3];          // OutOfBoundsException
+$stringy[2] = 'a';    // Exception
+```
+
 ## Methods
 
 In the list below, any static method other than S::create refers to a method in
 `Stringy\StaticStringy`. For all others, they're found in `Stringy\Stringy`.
 Furthermore, all methods that return a Stringy object or string do not modify
-the original.
+the original. Stringy objects are immutable.
 
 *Note: If `$encoding` is not given, it defaults to `mb_internal_encoding()`.*
 
@@ -133,9 +175,9 @@ the original.
 
 $stringy->at(int $index)
 
-S::substr(int $index [, string $encoding ])
+S::at(int $index [, string $encoding ])
 
-Returns the character of the string at $index, with indexes starting at 0.
+Returns the character at $index, with indexes starting at 0.
 
 ```php
 S::create('fòô bàř', 'UTF-8')->at(6);
@@ -148,15 +190,28 @@ $stringy->camelize();
 
 S::camelize(string $str [, string $encoding ])
 
-Returns a camelCase version of the supplied string. Trims surrounding
-spaces, capitalizes letters following digits, spaces, dashes and
-underscores, and removes spaces, dashes, underscores.
+Returns a camelCase version of the string. Trims surrounding spaces,
+capitalizes letters following digits, spaces, dashes and underscores,
+and removes spaces, dashes, as well as underscores.
 
 ```php
 S::create('Camel-Case')->camelize();
 S::camelize('Camel-Case');  // 'camelCase'
 ```
 
+#### chars
+
+$stringy->chars();
+
+S::chars(string $str [, string $encoding ])
+
+Returns an array consisting of the characters in the string.
+
+```php
+S::create('Fòô Bàř', 'UTF-8')->chars();
+S::chars('Fòô Bàř', 'UTF-8');  // array(F', 'ò', 'ô', ' ', 'B', 'à', 'ř')
+```
+
 #### collapseWhitespace
 
 $stringy->collapseWhitespace()
@@ -187,19 +242,19 @@ S::create('Ο συγγραφέας είπε', 'UTF-8')->contains('συγγραφ
 S::contains('Ο συγγραφέας είπε', 'συγγραφέας', 'UTF-8');  // true
 ```
 
-#### count
+#### countSubstr
 
-$stringy->count(string $substring [, boolean $caseSensitive = true ])
+$stringy->countSubstr(string $substring [, boolean $caseSensitive = true ])
 
-S::count(string $str, string $substring [, boolean $caseSensitive = true [, string $encoding ]])
+S::countSubstr(string $str, string $substring [, boolean $caseSensitive = true [, string $encoding ]])
 
 Returns the number of occurrences of $substring in the given string.
 By default, the comparison is case-sensitive, but can be made insensitive
 by setting $caseSensitive to false.
 
 ```php
-S::create('Ο συγγραφέας είπε', 'UTF-8')->count('α');
-S::count('Ο συγγραφέας είπε', 'α', 'UTF-8');  // 2
+S::create('Ο συγγραφέας είπε', 'UTF-8')->countSubstr('α');
+S::countSubstr('Ο συγγραφέας είπε', 'α', 'UTF-8');  // 2
 ```
 
 #### create
@@ -577,7 +632,7 @@ $stringy->removeLeft(string $substring)
 
 S::removeLeft(string $str, string $substring [, string $encoding ])
 
-Returns a new string with the prefix $substring removed, if it was present.
+Returns a new string with the prefix $substring removed, if present.
 
 ```php
 S::create('fòô bàř', 'UTF-8')->removeLeft('fòô ');
@@ -590,7 +645,7 @@ $stringy->removeRight(string $substring)
 
 S::removeRight(string $str, string $substring [, string $encoding ])
 
-Returns a new string with the suffix $substring removed, if it was present.
+Returns a new string with the suffix $substring removed, if present.
 
 ```php
 S::create('fòô bàř', 'UTF-8')->removeRight(' bàř');
@@ -630,8 +685,8 @@ $stringy->safeTruncate(int $length, [, string $substring = '' ])
 S::safeTruncate(string $str, int $length, [, string $substring = '' [, string $encoding ]])
 
 Truncates the string to a given length, while ensuring that it does not
-chop words. If $substring is provided, and truncating occurs, the string
-is further truncated so that the substring may be appended without
+split words. If $substring is provided, and truncating occurs, the
+string is further truncated so that the substring may be appended without
 exceeding the desired length.
 
 ```php
@@ -660,10 +715,10 @@ $stringy->slugify([ string $replacement = '-' ])
 S::slugify(string $str [, string $replacement = '-' ])
 
 Converts the string into an URL slug. This includes replacing non-ASCII
-characters with their closest ASCII equivalents, removing non-alphanumeric
-and non-ASCII characters, and replacing whitespace with $replacement.
-The replacement defaults to a single dash, and the string is also
-converted to lowercase.
+characters with their closest ASCII equivalents, removing remaining
+non-ASCII and non-alphanumeric characters, and replacing whitespace with
+$replacement. The replacement defaults to a single dash, and the string
+is also converted to lowercase.
 
 ```php
 S::create('Using strings like fòô bàř')->slugify();
@@ -747,9 +802,8 @@ $stringy->titleize([ string $encoding ])
 S::titleize(string $str [, array $ignore [, string $encoding ]])
 
 Returns a trimmed string with the first letter of each word capitalized.
-Ignores the case of other letters, allowing for the use of acronyms.
-Also accepts an array, $ignore, allowing you to list words not to be
-capitalized.
+Ignores the case of other letters, preserving any acronyms. Also accepts
+an array, $ignore, allowing you to list words not to be capitalized.
 
 ```php
 $ignore = array('at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the');
@@ -853,8 +907,8 @@ truncating occurs, the string is further truncated so that the substring
 may be appended without exceeding the desired length.
 
 ```php
-S::create('What are your plans today?')->safeTruncate(19, '...');
-S::safeTruncate('What are your plans today?', 19, '...');  // 'What are your pl...'
+S::create('What are your plans today?')->truncate(19, '...');
+S::truncate('What are your plans today?', 19, '...');  // 'What are your pl...'
 ```
 
 #### underscored

composer.json

@@ -17,7 +17,11 @@
     "require": {
         "php": ">=5.3.0"
     },
+    "support": {
+        "issues": "https://github.com/danielstjules/Stringy/issues",
+        "source": "https://github.com/danielstjules/Stringy"
+    },
     "autoload": {
-        "psr-0": { "Stringy": "src/" }
+        "psr-4": { "Stringy\\": "src/" }
     }
 }

phpunit.xml.dist

@@ -5,7 +5,7 @@
          syntaxCheck="false">
     <testsuites>
         <testsuite name="Stringy">
-            <directory>tests/Stringy</directory>
+            <directory>tests</directory>
         </testsuite>
     </testsuites>
 </phpunit>

src/StaticStringy.php

@@ -0,0 +1,792 @@
+<?php
+
+namespace Stringy;
+
+class StaticStringy
+{
+    /**
+     * Returns an array consisting of the characters in the string.
+     *
+     * @param  string $str      String for which to return the chars
+     * @param  string $encoding The character encoding
+     * @return array  An array of string chars
+     */
+    public static function chars($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->chars();
+    }
+
+    /**
+     * Converts the first character of the supplied string to upper case.
+     *
+     * @param  string $str      String to modify
+     * @param  string $encoding The character encoding
+     * @return string String with the first character being upper case
+     */
+    public static function upperCaseFirst($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->upperCaseFirst();
+    }
+
+    /**
+     * Converts the first character of the supplied string to lower case.
+     *
+     * @param  string $str      String to modify
+     * @param  string $encoding The character encoding
+     * @return string String with the first character being lower case
+     */
+    public static function lowerCaseFirst($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->lowerCaseFirst();
+    }
+
+    /**
+     * Returns a camelCase version of the string. Trims surrounding spaces,
+     * capitalizes letters following digits, spaces, dashes and underscores,
+     * and removes spaces, dashes, as well as underscores.
+     *
+     * @param  string $str      String to convert to camelCase
+     * @param  string $encoding The character encoding
+     * @return string String in camelCase
+     */
+    public static function camelize($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->camelize();
+    }
+
+    /**
+     * Returns an UpperCamelCase version of the supplied string. It trims
+     * surrounding spaces, capitalizes letters following digits, spaces, dashes
+     * and underscores, and removes spaces, dashes, underscores.
+     *
+     * @param  string $str      String to convert to UpperCamelCase
+     * @param  string $encoding The character encoding
+     * @return string String in UpperCamelCase
+     */
+    public static function upperCamelize($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->upperCamelize();
+    }
+
+    /**
+     * Returns a lowercase and trimmed string separated by dashes. Dashes are
+     * inserted before uppercase characters (with the exception of the first
+     * character of the string), and in place of spaces as well as underscores.
+     *
+     * @param  string $str      String to convert
+     * @param  string $encoding The character encoding
+     * @return string Dasherized string
+     */
+    public static function dasherize($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->dasherize();
+    }
+
+    /**
+     * Returns a lowercase and trimmed string separated by underscores.
+     * Underscores are inserted before uppercase characters (with the exception
+     * of the first character of the string), and in place of spaces as well as
+     * dashes.
+     *
+     * @param  string  $str      String to convert
+     * @param  string  $encoding The character encoding
+     * @return string  Underscored string
+     */
+    public static function underscored($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->underscored();
+    }
+
+    /**
+     * Returns a case swapped version of the string.
+     *
+     * @param  string $str      String to swap case
+     * @param  string $encoding The character encoding
+     * @return string String with each character's case swapped
+     */
+    public static function swapCase($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->swapCase();
+    }
+
+    /**
+     * Returns a trimmed string with the first letter of each word capitalized.
+     * Ignores the case of other letters, preserving any acronyms. Also accepts
+     * an array, $ignore, allowing you to list words not to be capitalized.
+     *
+     * @param  string $str      String to titleize
+     * @param  string $encoding The character encoding
+     * @param  array  $ignore   An array of words not to capitalize
+     * @return string Titleized string
+     */
+    public static function titleize($str, $ignore = null, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->titleize($ignore);
+    }
+
+    /**
+     * Capitalizes the first word of the string, replaces underscores with
+     * spaces, and strips '_id'.
+     *
+     * @param  string $str      String to humanize
+     * @param  string $encoding The character encoding
+     * @return string A humanized string
+     */
+    public static function humanize($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->humanize();
+    }
+
+    /**
+     * Returns a string with smart quotes, ellipsis characters, and dashes from
+     * Windows-1252 (commonly used in Word documents) replaced by their ASCII
+     * equivalents.
+     *
+     * @param  string $str String to remove special chars
+     * @return string String with those characters removed
+     */
+    public static function tidy($str)
+    {
+        return (string) Stringy::create($str)->tidy();
+    }
+
+    /**
+     * Trims the string and replaces consecutive whitespace characters with a
+     * single space. This includes tabs and newline characters, as well as
+     * multibyte whitespace such as the thin space and ideographic space.
+     *
+     * @param  string $str      The string to cleanup whitespace
+     * @param  string $encoding The character encoding
+     * @return string The trimmed string with condensed whitespace
+     */
+    public static function collapseWhitespace($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->collapseWhitespace();
+    }
+
+    /**
+     * Returns an ASCII version of the string. A set of non-ASCII characters are
+     * replaced with their closest ASCII counterparts, and the rest are removed.
+     *
+     * @param  string $str A string with non-ASCII characters
+     * @return string A string containing only ASCII characters
+     */
+    public static function toAscii($str)
+    {
+        return (string) Stringy::create($str)->toAscii();
+    }
+
+    /**
+     * Pads the string to a given length with $padStr. If length is less than
+     * or equal to the length of the string, no padding takes places. The
+     * default string used for padding is a space, and the default type (one of
+     * 'left', 'right', 'both') is 'right'. Throws an InvalidArgumentException
+     * if $padType isn't one of those 3 values.
+     *
+     * @param  string $str      String to pad
+     * @param  int    $length   Desired string length after padding
+     * @param  string $padStr   String used to pad, defaults to space
+     * @param  string $padType  One of 'left', 'right', 'both'
+     * @param  string $encoding The character encoding
+     * @return string The padded string
+     * @throws \InvalidArgumentException If $padType isn't one of 'right',
+     *         'left' or 'both'
+     */
+    public static function pad($str, $length, $padStr = ' ', $padType = 'right',
+                               $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->pad($length, $padStr, $padType);
+    }
+
+    /**
+     * Returns a new string of a given length such that the beginning of the
+     * string is padded. Alias for pad() with a $padType of 'left'.
+     *
+     * @param  string $str      String to pad
+     * @param  int    $length   Desired string length after padding
+     * @param  string $padStr   String used to pad, defaults to space
+     * @param  string $encoding The character encoding
+     * @return string The padded string
+     */
+    public static function padLeft($str, $length, $padStr = ' ', $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->padLeft($length, $padStr);
+    }
+
+    /**
+     * Returns a new string of a given length such that the end of the string
+     * is padded. Alias for pad() with a $padType of 'right'.
+     *
+     * @param  string $str      String to pad
+     * @param  int    $length   Desired string length after padding
+     * @param  string $padStr   String used to pad, defaults to space
+     * @param  string $encoding The character encoding
+     * @return string The padded string
+     */
+    public static function padRight($str, $length, $padStr = ' ', $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->padRight($length, $padStr);
+    }
+
+    /**
+     * Returns a new string of a given length such that both sides of the
+     * string are padded. Alias for pad() with a $padType of 'both'.
+     *
+     * @param  string $str      String to pad
+     * @param  int    $length   Desired string length after padding
+     * @param  string $padStr   String used to pad, defaults to space
+     * @param  string $encoding The character encoding
+     * @return string The padded string
+     */
+    public static function padBoth($str, $length, $padStr = ' ', $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->padBoth($length, $padStr);
+    }
+
+    /**
+     * Returns true if the string begins with $substring, false otherwise. By
+     * default, the comparison is case-sensitive, but can be made insensitive
+     * by setting $caseSensitive to false.
+     *
+     * @param  string $str           String to check the start of
+     * @param  string $substring     The substring to look for
+     * @param  bool   $caseSensitive Whether or not to enforce case-sensitivity
+     * @param  string $encoding      The character encoding
+     * @return bool   Whether or not $str starts with $substring
+     */
+    public static function startsWith($str, $substring, $caseSensitive = true,
+                                      $encoding = null)
+    {
+        return Stringy::create($str, $encoding)
+            ->startsWith($substring, $caseSensitive);
+    }
+
+    /**
+     * Returns true if the string ends with $substring, false otherwise. By
+     * default, the comparison is case-sensitive, but can be made insensitive
+     * by setting $caseSensitive to false.
+     *
+     * @param  string $str           String to check the end of
+     * @param  string $substring     The substring to look for
+     * @param  bool   $caseSensitive Whether or not to enforce case-sensitivity
+     * @param  string $encoding      The character encoding
+     * @return bool   Whether or not $str ends with $substring
+     */
+    public static function endsWith($str, $substring, $caseSensitive = true,
+                                    $encoding = null)
+    {
+        return Stringy::create($str, $encoding)
+            ->endsWith($substring, $caseSensitive);
+    }
+
+    /**
+     * Converts each tab in the string to some number of spaces, as defined by
+     * $tabLength. By default, each tab is converted to 4 consecutive spaces.
+     *
+     * @param  string $str       String to convert tabs to spaces
+     * @param  int    $tabLength Number of spaces to replace each tab with
+     * @return string String with tabs switched to spaces
+     */
+    public static function toSpaces($str, $tabLength = 4)
+    {
+        return (string) Stringy::create($str)->toSpaces($tabLength);
+    }
+
+    /**
+     * Converts each occurrence of some consecutive number of spaces, as
+     * defined by $tabLength, to a tab. By default, each 4 consecutive spaces
+     * are converted to a tab.
+     *
+     * @param  string $str       String to convert spaces to tabs
+     * @param  int    $tabLength Number of spaces to replace with a tab
+     * @return string String with spaces switched to tabs
+     */
+    public static function toTabs($str, $tabLength = 4)
+    {
+        return (string) Stringy::create($str)->toTabs($tabLength);
+    }
+
+    /**
+     * Converts all characters in the string to lowercase. An alias for PHP's
+     * mb_strtolower().
+     *
+     * @param  string $str      String to convert case
+     * @param  string $encoding The character encoding
+     * @return string The lowercase string
+     */
+    public static function toLowerCase($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->toLowerCase();
+    }
+
+    /**
+     * Converts all characters in the string to uppercase. An alias for PHP's
+     * mb_strtoupper().
+     *
+     * @param  string $str      String to convert case
+     * @param  string $encoding The character encoding
+     * @return string The uppercase string
+     */
+    public static function toUpperCase($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->toUpperCase();
+    }
+
+    /**
+     * Converts the string into an URL slug. This includes replacing non-ASCII
+     * characters with their closest ASCII equivalents, removing remaining
+     * non-ASCII and non-alphanumeric characters, and replacing whitespace with
+     * $replacement. The replacement defaults to a single dash, and the string
+     * is also converted to lowercase.
+     *
+     * @param  string $str         Text to transform into an URL slug
+     * @param  string $replacement The string used to replace whitespace
+     * @return string The corresponding URL slug
+     */
+    public static function slugify($str, $replacement = '-')
+    {
+        return (string) Stringy::create($str)->slugify($replacement);
+    }
+
+    /**
+     * Returns true if the string contains $needle, false otherwise. By default,
+     * the comparison is case-sensitive, but can be made insensitive by setting
+     * $caseSensitive to false.
+     *
+     * @param  string $haystack      String being checked
+     * @param  string $needle        Substring to look for
+     * @param  bool   $caseSensitive Whether or not to enforce case-sensitivity
+     * @param  string $encoding      The character encoding
+     * @return bool   Whether or not $haystack contains $needle
+     */
+    public static function contains($haystack, $needle, $caseSensitive = true,
+                                    $encoding = null)
+    {
+        return Stringy::create($haystack, $encoding)
+            ->contains($needle, $caseSensitive);
+    }
+
+    /**
+     * Surrounds a string with the given substring.
+     *
+     * @param  string $str       The string to surround
+     * @param  string $substring The substring to add to both sides
+     * @return string The string with the substring prepended and appended
+     */
+    public static function surround($str, $substring)
+    {
+        return (string) Stringy::create($str)->surround($substring);
+    }
+
+    /**
+     * Inserts $substring into the string at the $index provided.
+     *
+     * @param  string $str       String to insert into
+     * @param  string $substring String to be inserted
+     * @param  int    $index     The index at which to insert the substring
+     * @param  string $encoding  The character encoding
+     * @return string The resulting string after the insertion
+     */
+    public static function insert($str, $substring, $index, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->insert($substring, $index);
+    }
+
+    /**
+     * Truncates the string to a given length. If $substring is provided, and
+     * truncating occurs, the string is further truncated so that the substring
+     * may be appended without exceeding the desired length.
+     *
+     * @param  string $str       String to truncate
+     * @param  int    $length    Desired length of the truncated string
+     * @param  string $substring The substring to append if it can fit
+     * @param  string $encoding  The character encoding
+     * @return string The resulting string after truncating
+     */
+    public static function truncate($str, $length, $substring = '',
+                                    $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->truncate($length, $substring);
+    }
+
+    /**
+     * Truncates the string to a given length, while ensuring that it does not
+     * split words. If $substring is provided, and truncating occurs, the
+     * string is further truncated so that the substring may be appended without
+     * exceeding the desired length.
+     *
+     * @param  string $str       String to truncate
+     * @param  int    $length    Desired length of the truncated string
+     * @param  string $substring The substring to append if it can fit
+     * @param  string $encoding  The character encoding
+     * @return string The resulting string after truncating
+     */
+    public static function safeTruncate($str, $length, $substring = '',
+                                    $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->safeTruncate($length, $substring);
+    }
+
+    /**
+     * Returns a reversed string. A multibyte version of strrev().
+     *
+     * @param  string $str      String to reverse
+     * @param  string $encoding The character encoding
+     * @return string The reversed string
+     */
+    public static function reverse($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->reverse();
+    }
+
+    /**
+     * A multibyte str_shuffle() function. It returns a string with its
+     * characters in random order.
+     *
+     * @param  string $str      String to shuffle
+     * @param  string $encoding The character encoding
+     * @return string The shuffled string
+     */
+    public static function shuffle($str, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->shuffle();
+    }
+
+    /**
+     * Returns the trimmed string. An alias for PHP's trim() function.
+     *
+     * @param  string $str String to trim
+     * @return string Trimmed $str
+     */
+    public static function trim($str)
+    {
+        return trim($str);
+    }
+
+    /**
+     * Returns the longest common prefix between the string and $otherStr.
+     *
+     * @param  string $str      First string for comparison
+     * @param  string $otherStr Second string for comparison
+     * @param  string $encoding The character encoding
+     * @return string The longest common prefix
+     */
+    public static function longestCommonPrefix($str, $otherStr, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->longestCommonPrefix($otherStr);
+    }
+
+    /**
+     * Returns the longest common suffix between the string and $otherStr.
+     *
+     * @param  string $str      First string for comparison
+     * @param  string $otherStr Second string for comparison
+     * @param  string $encoding The character encoding
+     * @return string The longest common suffix
+     */
+    public static function longestCommonSuffix($str, $otherStr, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->longestCommonSuffix($otherStr);
+    }
+
+    /**
+     * Returns the longest common substring between the string and $otherStr.
+     * In the case of ties, it returns that which occurs first.
+     *
+     * @param  string $str      First string for comparison
+     * @param  string $otherStr Second string for comparison
+     * @param  string $encoding The character encoding
+     * @return string The longest common substring
+     */
+    public static function longestCommonSubstring($str, $otherStr,
+                                                  $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->longestCommonSubstring($otherStr);
+    }
+
+    /**
+     * Returns the length of the string. An alias for PHP's mb_strlen() function.
+     *
+     * @param  string $str      The string to get the length of
+     * @param  string $encoding The character encoding
+     * @return int    The number of characters in $str given the encoding
+     */
+    public static function length($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->length();
+    }
+
+    /**
+     * Returns the substring beginning at $start with the specified $length.
+     * It differs from the mb_substr() function in that providing a $length of
+     * null will return the rest of the string, rather than an empty string.
+     *
+     * @param  string $str      The string to get the length of
+     * @param  int    $start    Position of the first character to use
+     * @param  int    $length   Maximum number of characters used
+     * @param  string $encoding The character encoding
+     * @return string The substring of $str
+     */
+    public static function substr($str, $start, $length = null, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->substr($start, $length);
+    }
+
+    /**
+     * Returns the character at $index, with indexes starting at 0.
+     *
+     * @param  string $str      The string from which to get the char
+     * @param  int    $index    Position of the character
+     * @param  string $encoding The character encoding
+     * @return string The character at $index
+     */
+    public static function at($str, $index, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->at($index);
+    }
+
+    /**
+     * Returns the first $n characters of the string.
+     *
+     * @param  string $str      The string from which to get the substring
+     * @param  int    $n        Number of chars to retrieve from the start
+     * @param  string $encoding The character encoding
+     * @return string The first $n characters
+     */
+    public static function first($str, $n, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->first($n);
+    }
+
+    /**
+     * Returns the last $n characters of the string.
+     *
+     * @param  string $str      The string from which to get the substring
+     * @param  int    $n        Number of chars to retrieve from the end
+     * @param  string $encoding The character encoding
+     * @return string The last $n characters
+     */
+    public static function last($str, $n, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->last($n);
+    }
+
+    /**
+     * Ensures that the string begins with $substring. If it doesn't, it's
+     * prepended.
+     *
+     * @param  string $str       The string to modify
+     * @param  string $substring The substring to add if not present
+     * @param  string $encoding  The character encoding
+     * @return string The string prefixed by the $substring
+     */
+    public static function ensureLeft($str, $substring, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->ensureLeft($substring);
+    }
+
+    /**
+     * Ensures that the string begins with $substring. If it doesn't, it's
+     * appended.
+     *
+     * @param  string $str       The string to modify
+     * @param  string $substring The substring to add if not present
+     * @param  string $encoding  The character encoding
+     * @return string The string suffixed by the $substring
+     */
+    public static function ensureRight($str, $substring, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->ensureRight($substring);
+    }
+
+    /**
+     * Returns a new string with the prefix $substring removed, if present.
+     *
+     * @param  string $str       String from which to remove the prefix
+     * @param  string $substring The prefix to remove
+     * @param  string $encoding  The character encoding
+     * @return string The string without the prefix $substring
+     */
+    public static function removeLeft($str, $substring, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->removeLeft($substring);
+    }
+
+    /**
+     * Returns a new string with the suffix $substring removed, if present.
+     *
+     * @param  string $str       String from which to remove the suffix
+     * @param  string $substring The suffix to remove
+     * @param  string $encoding  The character encoding
+     * @return string The string without the suffix $substring
+     */
+    public static function removeRight($str, $substring, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->removeRight($substring);
+    }
+
+    /**
+     * Returns true if the string contains only alphabetic chars, false
+     * otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only alphabetic chars
+     */
+    public static function isAlpha($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isAlpha();
+    }
+
+    /**
+     * Returns true if the string contains only alphabetic and numeric chars,
+     * false otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only alphanumeric chars
+     */
+    public static function isAlphanumeric($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isAlphanumeric();
+    }
+
+    /**
+     * Returns true if the string contains only whitespace chars, false
+     * otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only whitespace characters
+     */
+    public static function isBlank($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isBlank();
+    }
+
+    /**
+     * Returns true if the string is JSON, false otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str is JSON
+     */
+    public static function isJson($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isJson();
+    }
+
+    /**
+     * Returns true if the string contains only lower case chars, false
+     * otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only lower case characters
+     */
+    public static function isLowerCase($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isLowerCase();
+    }
+
+    /**
+     * Returns true if the string is serialized, false otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str is serialized
+     */
+    public static function isSerialized($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isSerialized();
+    }
+
+    /**
+     * Returns true if the string contains only upper case chars, false
+     * otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only upper case characters
+     */
+    public static function isUpperCase($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isUpperCase();
+    }
+
+    /**
+     * Returns true if the string contains only hexadecimal chars, false
+     * otherwise.
+     *
+     * @param  string $str      String to check
+     * @param  string $encoding The character encoding
+     * @return bool   Whether or not $str contains only hexadecimal characters
+     */
+    public static function isHexadecimal($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->isHexadecimal();
+    }
+
+    /**
+     * Returns the number of occurrences of $substring in the given string.
+     * By default, the comparison is case-sensitive, but can be made insensitive
+     * by setting $caseSensitive to false.
+     *
+     * @param  string $str           The string to search through
+     * @param  string $substring     The substring to search for
+     * @param  bool   $caseSensitive Whether or not to enforce case-sensitivity
+     * @param  string $encoding      The character encoding
+     * @return int    The number of $substring occurrences
+     */
+    public static function countSubstr($str, $substring, $caseSensitive = true,
+                                       $encoding = null)
+    {
+        return Stringy::create($str, $encoding)
+            ->countSubstr($substring, $caseSensitive);
+    }
+
+    /**
+     * Replaces all occurrences of $search in $str by $replacement.
+     *
+     * @param  string $str         The haystack to search through
+     * @param  string $search      The needle to search for
+     * @param  string $replacement The string to replace with
+     * @param  string $encoding    The character encoding
+     * @return string The resulting string after the replacements
+     */
+    public static function replace($str, $search, $replacement, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->replace($search,$replacement);
+    }
+
+    /**
+     * Replaces all occurrences of $pattern in $str by $replacement. An alias
+     * for mb_ereg_replace(). Note that the 'i' option with multibyte patterns
+     * in mb_ereg_replace() requires PHP 5.4+. This is due to a lack of support
+     * in the bundled version of Oniguruma in PHP 5.3.
+     *
+     * @param  string $str         The haystack to search through
+     * @param  string $pattern     The regular expression pattern
+     * @param  string $replacement The string to replace with
+     * @param  string $options     Matching conditions to be used
+     * @param  string $encoding    The character encoding
+     * @return string The resulting string after the replacements
+     */
+    public static function regexReplace($str, $pattern, $replacement,
+                                        $options = 'msr', $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)
+            ->regexReplace($pattern, $replacement, $options, $encoding);
+    }
+}

src/Stringy/StaticStringy.php

@@ -1,769 +0,0 @@
-<?php
-
-namespace Stringy;
-
-class StaticStringy
-{
-    /**
-     * Converts the first character of the supplied string to upper case.
-     *
-     * @param   string  $str       String to modify
-     * @param   string  $encoding  The character encoding
-     * @return  string  String with the first character being upper case
-     */
-    public static function upperCaseFirst($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->upperCaseFirst();
-    }
-
-    /**
-     * Converts the first character of the supplied string to lower case.
-     *
-     * @param   string  $str       String to modify
-     * @param   string  $encoding  The character encoding
-     * @return  string  String with the first character being lower case
-     */
-    public static function lowerCaseFirst($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->lowerCaseFirst();
-    }
-
-    /**
-     * Returns a camelCase version of the supplied string. Trims surrounding
-     * spaces, capitalizes letters following digits, spaces, dashes and
-     * underscores, and removes spaces, dashes, underscores.
-     *
-     * @param   string  $str       String to convert to camelCase
-     * @param   string  $encoding  The character encoding
-     * @return  string  String in camelCase
-     */
-    public static function camelize($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->camelize();
-    }
-
-    /**
-     * Returns an UpperCamelCase version of the supplied string. It trims
-     * surrounding spaces, capitalizes letters following digits, spaces, dashes
-     * and underscores, and removes spaces, dashes, underscores.
-     *
-     * @param   string  $str       String to convert to UpperCamelCase
-     * @param   string  $encoding  The character encoding
-     * @return  string  String in UpperCamelCase
-     */
-    public static function upperCamelize($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->upperCamelize();
-    }
-
-    /**
-     * Returns a lowercase and trimmed string separated by dashes. Dashes are
-     * inserted before uppercase characters (with the exception of the first
-     * character of the string), and in place of spaces as well as underscores.
-     *
-     * @param   string  $str       String to convert
-     * @param   string  $encoding  The character encoding
-     * @return  string  Dasherized string
-     */
-    public static function dasherize($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->dasherize();
-    }
-
-    /**
-     * Returns a lowercase and trimmed string separated by underscores.
-     * Underscores are inserted before uppercase characters (with the exception
-     * of the first character of the string), and in place of spaces as well as
-     * dashes.
-     *
-     * @param   string  $str       String to convert
-     * @param   string  $encoding  The character encoding
-     * @return  string  Underscored string
-     */
-    public static function underscored($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->underscored();
-    }
-
-    /**
-     * Returns a case swapped version of the string.
-     *
-     * @param   string  $str       String to swap case
-     * @param   string  $encoding  The character encoding
-     * @return  string  String with each character's case swapped
-     */
-    public static function swapCase($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->swapCase();
-    }
-
-    /**
-     * Returns a trimmed string with the first letter of each word capitalized.
-     * Ignores the case of other letters, allowing for the use of acronyms.
-     * Also accepts an array, $ignore, allowing you to list words not to be
-     * capitalized.
-     *
-     * @param   string  $str       String to titleize
-     * @param   string  $encoding  The character encoding
-     * @param   array   $ignore    An array of words not to capitalize
-     * @return  string  Titleized string
-     */
-    public static function titleize($str, $ignore = null, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->titleize($ignore);
-    }
-
-    /**
-     * Capitalizes the first word of the string, replaces underscores with
-     * spaces, and strips '_id'.
-     *
-     * @param   string  $str       String to humanize
-     * @param   string  $encoding  The character encoding
-     * @return  string  A humanized string
-     */
-    public static function humanize($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->humanize();
-    }
-
-    /**
-     * Returns a string with smart quotes, ellipsis characters, and dashes from
-     * Windows-1252 (commonly used in Word documents) replaced by their ASCII
-     * equivalents.
-     *
-     * @param   string  $str       String to remove special chars
-     * @return  string  String with those characters removed
-     */
-    public static function tidy($str)
-    {
-        return (string) Stringy::create($str)->tidy();
-    }
-
-    /**
-     * Trims the string and replaces consecutive whitespace characters with a
-     * single space. This includes tabs and newline characters, as well as
-     * multibyte whitespace such as the thin space and ideographic space.
-     *
-     * @param   string  $str       The string to cleanup whitespace
-     * @param   string  $encoding  The character encoding
-     * @return  string  The trimmed string with condensed whitespace
-     */
-    public static function collapseWhitespace($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->collapseWhitespace();
-    }
-
-    /**
-     * Returns an ASCII version of the string. A set of non-ASCII characters are
-     * replaced with their closest ASCII counterparts, and the rest are removed.
-     *
-     * @param   string  $str  A string with non-ASCII characters
-     * @return  string  A string containing only ASCII characters
-     */
-    public static function toAscii($str)
-    {
-        return (string) Stringy::create($str)->toAscii();
-    }
-
-    /**
-     * Pads the string to a given length with $padStr. If length is less than
-     * or equal to the length of the string, no padding takes places. The default
-     * string used for padding is a space, and the default type (one of 'left',
-     * 'right', 'both') is 'right'. Throws an InvalidArgumentException if
-     * $padType isn't one of those 3 values.
-     *
-     * @param   string  $str       String to pad
-     * @param   int     $length    Desired string length after padding
-     * @param   string  $padStr    String used to pad, defaults to space
-     * @param   string  $padType   One of 'left', 'right', 'both'
-     * @param   string  $encoding  The character encoding
-     * @return  string  The padded string
-     * @throws  \InvalidArgumentException If $padType isn't one of 'right',
-     *          'left' or 'both'
-     */
-    public static function pad($str, $length, $padStr = ' ', $padType = 'right',
-                               $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->pad($length, $padStr, $padType);
-    }
-
-    /**
-     * Returns a new string of a given length such that the beginning of the
-     * string is padded. Alias for pad() with a $padType of 'left'.
-     *
-     * @param   string  $str       String to pad
-     * @param   int     $length    Desired string length after padding
-     * @param   string  $padStr    String used to pad, defaults to space
-     * @param   string  $encoding  The character encoding
-     * @return  string  The padded string
-     */
-    public static function padLeft($str, $length, $padStr = ' ', $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->padLeft($length, $padStr);
-    }
-
-    /**
-     * Returns a new string of a given length such that the end of the string is
-     * padded. Alias for pad() with a $padType of 'right'.
-     *
-     * @param   string  $str       String to pad
-     * @param   int     $length    Desired string length after padding
-     * @param   string  $padStr    String used to pad, defaults to space
-     * @param   string  $encoding  The character encoding
-     * @return  string  The padded string
-     */
-    public static function padRight($str, $length, $padStr = ' ', $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->padRight($length, $padStr);
-    }
-
-    /**
-     * Returns a new string of a given length such that both sides of the string
-     * string are padded. Alias for pad() with a $padType of 'both'.
-     *
-     * @param   string  $str       String to pad
-     * @param   int     $length    Desired string length after padding
-     * @param   string  $padStr    String used to pad, defaults to space
-     * @param   string  $encoding  The character encoding
-     * @return  string  The padded string
-     */
-    public static function padBoth($str, $length, $padStr = ' ', $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->padBoth($length, $padStr);
-    }
-
-    /**
-     * Returns true if the string begins with $substring, false otherwise.
-     * By default, the comparison is case-sensitive, but can be made insensitive
-     * by setting $caseSensitive to false.
-     *
-     * @param   string  $str            String to check the start of
-     * @param   string  $substring      The substring to look for
-     * @param   bool    $caseSensitive  Whether or not to enforce case-sensitivity
-     * @param   string  $encoding       The character encoding
-     * @return  bool    Whether or not $str starts with $substring
-     */
-    public static function startsWith($str, $substring, $caseSensitive = true,
-                                      $encoding = null)
-    {
-        return Stringy::create($str, $encoding)
-                      ->startsWith($substring, $caseSensitive);
-    }
-
-    /**
-     * Returns true if the string ends with $substring, false otherwise. By
-     * default, the comparison is case-sensitive, but can be made insensitive by
-     * setting $caseSensitive to false.
-     *
-     * @param   string  $str            String to check the end of
-     * @param   string  $substring      The substring to look for
-     * @param   bool    $caseSensitive  Whether or not to enforce case-sensitivity
-     * @param   string  $encoding       The character encoding
-     * @return  bool    Whether or not $str ends with $substring
-     */
-    public static function endsWith($str, $substring, $caseSensitive = true,
-                                    $encoding = null)
-    {
-        return Stringy::create($str, $encoding)
-                      ->endsWith($substring, $caseSensitive);
-    }
-
-    /**
-     * Converts each tab in the string to some number of spaces, as defined by
-     * $tabLength. By default, each tab is converted to 4 consecutive spaces.
-     *
-     * @param   string  $str        String to convert tabs to spaces
-     * @param   int     $tabLength  Number of spaces to replace each tab with
-     * @return  string  String with tabs switched to spaces
-     */
-    public static function toSpaces($str, $tabLength = 4)
-    {
-        return (string) Stringy::create($str)->toSpaces($tabLength);
-    }
-
-    /**
-     * Converts each occurrence of some consecutive number of spaces, as defined
-     * by $tabLength, to a tab. By default, each 4 consecutive spaces are
-     * converted to a tab.
-     *
-     * @param   string  $str        String to convert spaces to tabs
-     * @param   int     $tabLength  Number of spaces to replace with a tab
-     * @return  string  String with spaces switched to tabs
-     */
-    public static function toTabs($str, $tabLength = 4)
-    {
-        return (string) Stringy::create($str)->toTabs($tabLength);
-    }
-
-    /**
-     * Converts all characters in the string to lowercase. An alias for PHP's
-     * mb_strtolower().
-     *
-     * @param   string  $str       String to convert case
-     * @param   string  $encoding  The character encoding
-     * @return  string  The lowercase string
-     */
-    public static function toLowerCase($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->toLowerCase();
-    }
-
-    /**
-     * Converts all characters in the string to uppercase. An alias for PHP's
-     * mb_strtoupper().
-     *
-     * @param   string  $str       String to convert case
-     * @param   string  $encoding  The character encoding
-     * @return  string  The uppercase string
-     */
-    public static function toUpperCase($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->toUpperCase();
-    }
-
-    /**
-     * Converts the string into an URL slug. This includes replacing non-ASCII
-     * characters with their closest ASCII equivalents, removing non-alphanumeric
-     * and non-ASCII characters, and replacing whitespace with $replacement.
-     * The replacement defaults to a single dash, and the string is also
-     * converted to lowercase.
-     *
-     * @param   string  $str          Text to transform into an URL slug
-     * @param   string  $replacement  The string used to replace whitespace
-     * @return  string  The corresponding URL slug
-     */
-    public static function slugify($str, $replacement = '-')
-    {
-        return (string) Stringy::create($str)->slugify($replacement);
-    }
-
-    /**
-     * Returns true if the string contains $needle, false otherwise. By default,
-     * the comparison is case-sensitive, but can be made insensitive by setting
-     * $caseSensitive to false.
-     *
-     * @param   string  $haystack       String being checked
-     * @param   string  $needle         Substring to look for
-     * @param   bool    $caseSensitive  Whether or not to enforce case-sensitivity
-     * @param   string  $encoding       The character encoding
-     * @return  bool    Whether or not $haystack contains $needle
-     */
-    public static function contains($haystack, $needle, $caseSensitive = true,
-                                    $encoding = null)
-    {
-        return Stringy::create($haystack, $encoding)->contains($needle, $caseSensitive);
-    }
-
-    /**
-     * Surrounds a string with the given substring.
-     *
-     * @param   string  $str        The string to surround
-     * @param   string  $substring  The substring to add to both sides
-     * @return  string  The string with the substring prepended and appended
-     */
-    public static function surround($str, $substring)
-    {
-        return (string) Stringy::create($str)->surround($substring);
-    }
-
-    /**
-     * Inserts $substring into the string at the $index provided.
-     *
-     * @param   string  $str        String to insert into
-     * @param   string  $substring  String to be inserted
-     * @param   int     $index      The index at which to insert the substring
-     * @param   string  $encoding   The character encoding
-     * @return  string  The resulting string after the insertion
-     */
-    public static function insert($str, $substring, $index, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->insert($substring, $index);
-    }
-
-    /**
-     * Truncates the string to a given length. If $substring is provided, and
-     * truncating occurs, the string is further truncated so that the substring
-     * may be appended without exceeding the desired length.
-     *
-     * @param   string  $str        String to truncate
-     * @param   int     $length     Desired length of the truncated string
-     * @param   string  $substring  The substring to append if it can fit
-     * @param   string  $encoding   The character encoding
-     * @return  string  The resulting string after truncating
-     */
-    public static function truncate($str, $length, $substring = '',
-                                    $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->truncate($length, $substring);
-    }
-
-    /**
-     * Truncates the string to a given length, while ensuring that it does not
-     * chop words. If $substring is provided, and truncating occurs, the string
-     * is further truncated so that the substring may be appended without
-     * exceeding the desired length.
-     *
-     * @param   string  $str        String to truncate
-     * @param   int     $length     Desired length of the truncated string
-     * @param   string  $substring  The substring to append if it can fit
-     * @param   string  $encoding   The character encoding
-     * @return  string  The resulting string after truncating
-     */
-    public static function safeTruncate($str, $length, $substring = '',
-                                    $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->safeTruncate($length, $substring);
-    }
-
-    /**
-     * Returns a reversed string. A multibyte version of strrev().
-     *
-     * @param   string  $str       String to reverse
-     * @param   string  $encoding  The character encoding
-     * @return  string  The reversed string
-     */
-    public static function reverse($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->reverse();
-    }
-
-    /**
-     * A multibyte str_shuffle() function. It returns a string with its
-     * characters in random order.
-     *
-     * @param   string  $str       String to shuffle
-     * @param   string  $encoding  The character encoding
-     * @return  string  The shuffled string
-     */
-    public static function shuffle($str, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->shuffle();
-    }
-
-    /**
-     * Returns the trimmed string. An alias for PHP's trim() function.
-     *
-     * @param   string  $str  String to trim
-     * @return  string  Trimmed $str
-     */
-    public static function trim($str)
-    {
-        return trim($str);
-    }
-
-    /**
-     * Returns the longest common prefix between the string and $otherStr.
-     *
-     * @param   string  $str       First string for comparison
-     * @param   string  $otherStr  Second string for comparison
-     * @param   string  $encoding  The character encoding
-     * @return  string  The longest common prefix
-     */
-    public static function longestCommonPrefix($str, $otherStr, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->longestCommonPrefix($otherStr);
-    }
-
-    /**
-     * Returns the longest common suffix between the string and $otherStr.
-     *
-     * @param   string  $str       First string for comparison
-     * @param   string  $otherStr  Second string for comparison
-     * @param   string  $encoding  The character encoding
-     * @return  string  The longest common suffix
-     */
-    public static function longestCommonSuffix($str, $otherStr, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->longestCommonSuffix($otherStr);
-    }
-
-    /**
-     * Returns the longest common substring between the string and $otherStr.
-     * In the case of ties, it returns that which occurs first.
-     *
-     * @param   string  $str       First string for comparison
-     * @param   string  $otherStr  Second string for comparison
-     * @param   string  $encoding  The character encoding
-     * @return  string  The longest common substring
-     */
-    public static function longestCommonSubstring($str, $otherStr,
-                                                  $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)
-                               ->longestCommonSubstring($otherStr);
-    }
-
-    /**
-     * Returns the length of the string. An alias for PHP's mb_strlen() function.
-     *
-     * @param   string  $str       The string to get the length of
-     * @param   string  $encoding  The character encoding
-     * @return  int     The number of characters in $str given the encoding
-     */
-    public static function length($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->length();
-    }
-
-    /**
-     * Returns the substring beginning at $start with the specified $length.
-     * It differs from the mb_substr() function in that providing a $length of
-     * null will return the rest of the string, rather than an empty string.
-     *
-     * @param   string  $str       The string to get the length of
-     * @param   int     $start     Position of the first character to use
-     * @param   int     $length    Maximum number of characters used
-     * @param   string  $encoding  The character encoding
-     * @return  string  The substring of $str
-     */
-    public static function substr($str, $start, $length = null, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->substr($start, $length);
-    }
-
-    /**
-     * Returns the character of the string at $index, with indexes starting at 0.
-     *
-     * @param   string   $str       The string from which to get the char
-     * @param   int      $index     Position of the character
-     * @param   string   $encoding  The character encoding
-     * @return  string   The character at $index
-     */
-    public static function at($str, $index, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->at($index);
-    }
-
-    /**
-     * Returns the first $n characters of the string.
-     *
-     * @param   string   $str       The string from which to get the substring
-     * @param   int      $n         Number of chars to retrieve from the start
-     * @param   string   $encoding  The character encoding
-     * @return  string   The first $n characters
-     */
-    public static function first($str, $n, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->first($n);
-    }
-
-    /**
-     * Returns the last $n characters of the string.
-     *
-     * @param   string   $str       The string from which to get the substring
-     * @param   int      $n         Number of chars to retrieve from the end
-     * @param   string   $encoding  The character encoding
-     * @return  string   The last $n characters
-     */
-    public static function last($str, $n, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->last($n);
-    }
-
-    /**
-     * Ensures that the string begins with $substring. If it doesn't, it's
-     * prepended.
-     *
-     * @param   string   $str        The string to modify
-     * @param   string   $substring  The substring to add if not present
-     * @param   string   $encoding   The character encoding
-     * @return  string   The string prefixed by the $substring
-     */
-    public static function ensureLeft($str, $substring, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->ensureLeft($substring);
-    }
-
-    /**
-     * Ensures that the string begins with $substring. If it doesn't, it's
-     * appended.
-     *
-     * @param   string   $str        The string to modify
-     * @param   string   $substring  The substring to add if not present
-     * @param   string   $encoding   The character encoding
-     * @return  string   The string suffixed by the $substring
-     */
-    public static function ensureRight($str, $substring, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->ensureRight($substring);
-    }
-
-    /**
-     * Returns a new string with the prefix $substring removed, if it was present.
-     *
-     * @param   string   $str        String from which to remove the prefix
-     * @param   string   $substring  The prefix to remove
-     * @param   string   $encoding   The character encoding
-     * @return  string   The string without the prefix $substring
-     */
-    public static function removeLeft($str, $substring, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->removeLeft($substring);
-    }
-
-    /**
-     * Returns a new string with the suffix $substring removed, if it was present.
-     *
-     * @param   string   $str        String from which to remove the suffix
-     * @param   string   $substring  The suffix to remove
-     * @param   string   $encoding   The character encoding
-     * @return  string   The string without the suffix $substring
-     */
-    public static function removeRight($str, $substring, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->removeRight($substring);
-    }
-
-    /**
-     * Returns true if the string contains only alphabetic chars, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only alphabetic chars
-     */
-    public static function isAlpha($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isAlpha();
-    }
-
-    /**
-     * Returns true if the string contains only alphabetic and numeric chars,
-     * false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only alphanumeric chars
-     */
-    public static function isAlphanumeric($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isAlphanumeric();
-    }
-
-    /**
-     * Returns true if the string contains only whitespace chars, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only whitespace characters
-     */
-    public static function isBlank($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isBlank();
-    }
-
-    /**
-     * Returns true if the string is JSON, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str is JSON
-     */
-    public static function isJson($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isJson();
-    }
-
-    /**
-     * Returns true if the string contains only lower case chars, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only lower case characters
-     */
-    public static function isLowerCase($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isLowerCase();
-    }
-
-    /**
-     * Returns true if the string is serialized, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str is serialized
-     */
-    public static function isSerialized($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isSerialized();
-    }
-
-    /**
-     * Returns true if the string contains only upper case chars, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only upper case characters
-     */
-    public static function isUpperCase($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isUpperCase();
-    }
-
-    /**
-     * Returns true if the string contains only hexadecimal chars, false otherwise.
-     *
-     * @param   string   $str       String to check
-     * @param   string   $encoding  The character encoding
-     * @return  bool     Whether or not $str contains only hexadecimal characters
-     */
-    public static function isHexadecimal($str, $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->isHexadecimal();
-    }
-
-    /**
-     * Returns the number of occurrences of $substring in the given string.
-     * By default, the comparison is case-sensitive, but can be made insensitive
-     * by setting $caseSensitive to false.
-     *
-     * @param   string   $str            The string to search through
-     * @param   string   $substring      The substring to search for
-     * @param   bool     $caseSensitive  Whether or not to enforce case-sensitivity
-     * @param   string   $encoding       The character encoding
-     * @return  int      The number of $substring occurrences
-     */
-    public static function count($str, $substring, $caseSensitive = true,
-                                 $encoding = null)
-    {
-        return Stringy::create($str, $encoding)->count($substring, $caseSensitive);
-    }
-
-    /**
-     * Replaces all occurrences of $search in $str by $replacement.
-     *
-     * @param   string   $str           The haystack to search through
-     * @param   string   $search        The needle to search for
-     * @param   string   $replacement   The string to replace with
-     * @param   string   $encoding      The character encoding
-     * @return  string   The resulting string after the replacements
-     */
-    public static function replace($str, $search, $replacement, $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->replace($search, $replacement);
-    }
-
-    /**
-     * Replaces all occurrences of $pattern in $str by $replacement. An alias
-     * for mb_ereg_replace(). Note that the 'i' option with multibyte patterns
-     * in mb_ereg_replace() requires PHP 5.4+. This is due to a lack of support
-     * in the bundled version of Oniguruma in PHP 5.3.
-     *
-     * @param   string   $str          The haystack to search through
-     * @param   string   $pattern      The regular expression pattern
-     * @param   string   $replacement  The string to replace with
-     * @param   string   $options      Matching conditions to be used
-     * @param   string   $encoding     The character encoding
-     * @return  string   The resulting string after the replacements
-     */
-    public static function regexReplace($str, $pattern, $replacement,
-                                        $options = 'msr', $encoding = null)
-    {
-        return (string) Stringy::create($str, $encoding)->regexReplace($pattern,
-            $replacement, $options, $encoding);
-    }
-}

tests/CommonTest.php

@@ -2,6 +2,15 @@
 
 abstract class CommonTest extends PHPUnit_Framework_TestCase
 {
+    public function charsProvider()
+    {
+        return array(
+            array(array(), ''),
+            array(array('T', 'e', 's', 't'), 'Test'),
+            array(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), 'Fòô Bàř', 'UTF-8')
+        );
+    }
+
     public function upperCaseFirstProvider()
     {
         return array(
@@ -798,7 +807,7 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
         );
     }
 
-    public function countProvider()
+    public function countSubstrProvider()
     {
         return array(
             array(0, '', 'foo'),

tests/StaticStringyTest.php

@@ -1,12 +1,25 @@
 <?php
 
-$base = realpath(dirname(__FILE__) . '/../..');
-require("$base/src/Stringy/StaticStringy.php");
+$base = realpath(dirname(__FILE__) . '/..');
+require("$base/src/StaticStringy.php");
 
 use Stringy\StaticStringy as S;
 
 class StaticStringyTestCase extends CommonTest
 {
+    /**
+     * @dataProvider charsProvider()
+     */
+    public function testChars($expected, $str, $encoding = null)
+    {
+        $result = S::chars($str, $encoding);
+        $this->assertInternalType('array', $result);
+        foreach ($result as $char) {
+            $this->assertInternalType('string', $char);
+        }
+        $this->assertEquals($expected, $result);
+    }
+
     /**
      * @dataProvider upperCaseFirstProvider()
      */
@@ -552,12 +565,12 @@ class StaticStringyTestCase extends CommonTest
     }
 
     /**
-     * @dataProvider countProvider()
+     * @dataProvider countSubstrProvider()
      */
-    public function testCount($expected, $str, $substring, $caseSensitive = true,
-                              $encoding = null)
+    public function testCountSubstr($expected, $str, $substring,
+                                    $caseSensitive = true, $encoding = null)
     {
-        $result = S::count($str, $substring, $caseSensitive, $encoding);
+        $result = S::countSubstr($str, $substring, $caseSensitive, $encoding);
         $this->assertInternalType('int', $result);
         $this->assertEquals($expected, $result);
     }

tests/StringyTest.php

@@ -1,7 +1,7 @@
 <?php
 
-$base = realpath(dirname(__FILE__) . '/../..');
-require("$base/src/Stringy/Stringy.php");
+$base = realpath(dirname(__FILE__) . '/..');
+require("$base/src/Stringy.php");
 
 use Stringy\Stringy as S;
 
@@ -70,6 +70,103 @@ class StringyTestCase extends CommonTest
         $this->assertEquals('FÒÔ bÀŘ', $result);
     }
 
+    public function testCount()
+    {
+        $stringy = S::create('Fòô', 'UTF-8');
+        $this->assertEquals(3, $stringy->count());
+        $this->assertEquals(3, count($stringy));
+    }
+
+    public function testGetIterator()
+    {
+        $stringy = S::create('Fòô Bàř', 'UTF-8');
+
+        $valResult = array();
+        foreach ($stringy as $char) {
+            $valResult[] = $char;
+        }
+
+        $keyValResult = array();
+        foreach ($stringy as $pos => $char) {
+            $keyValResult[$pos] = $char;
+        }
+
+        $this->assertEquals(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), $valResult);
+        $this->assertEquals(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), $keyValResult);
+    }
+
+    /**
+     * @dataProvider offsetExistsProvider()
+     */
+    public function testOffsetExists($expected, $offset)
+    {
+        $stringy = S::create('fòô', 'UTF-8');
+        $this->assertEquals($expected, $stringy->offsetExists($offset));
+        $this->assertEquals($expected, isset($stringy[$offset]));
+    }
+
+    public function offsetExistsProvider()
+    {
+        return array(
+            array(true, 0),
+            array(true, 2),
+            array(false, 3),
+            array(true, -1),
+            array(true, -3),
+            array(false, -4)
+        );
+    }
+
+    public function testOffsetGet()
+    {
+        $stringy = S::create('fòô', 'UTF-8');
+
+        $this->assertEquals('f', $stringy->offsetGet(0));
+        $this->assertEquals('ô', $stringy->offsetGet(2));
+
+        $this->assertEquals('ô', $stringy[2]);
+    }
+
+    /**
+     * @expectedException \OutOfBoundsException
+     */
+    public function testOffsetGetOutOfBounds()
+    {
+        $stringy = S::create('fòô', 'UTF-8');
+        $test = $stringy[3];
+    }
+
+    /**
+     * @expectedException \Exception
+     */
+    public function testOffsetSet()
+    {
+        $stringy = S::create('fòô', 'UTF-8');
+        $stringy[1] = 'invalid';
+    }
+
+    /**
+     * @expectedException \Exception
+     */
+    public function testOffsetUnset()
+    {
+        $stringy = S::create('fòô', 'UTF-8');
+        unset($stringy[1]);
+    }
+
+    /**
+     * @dataProvider charsProvider()
+     */
+    public function testChars($expected, $str, $encoding = null)
+    {
+        $result = S::create($str, $encoding)->chars();
+        $this->assertInternalType('array', $result);
+        foreach ($result as $char) {
+            $this->assertInternalType('string', $char);
+        }
+        $this->assertEquals($expected, $result);
+    }
+
     /**
      * @dataProvider upperCaseFirstProvider()
      */
@@ -690,13 +787,13 @@ class StringyTestCase extends CommonTest
     }
 
     /**
-     * @dataProvider countProvider()
+     * @dataProvider countSubstrProvider()
      */
-    public function testCount($expected, $str, $substring, $caseSensitive = true,
-                              $encoding = null)
+    public function testCountSubstr($expected, $str, $substring,
+                                    $caseSensitive = true, $encoding = null)
     {
         $stringy = S::create($str, $encoding);
-        $result = $stringy->count($substring, $caseSensitive);
+        $result = $stringy->countSubstr($substring, $caseSensitive);
         $this->assertInternalType('int', $result);
         $this->assertEquals($expected, $result);
         $this->assertEquals($str, $stringy);