[*]: added more API doc

[+]: optimized php-doc [+]: add more tests
voku · Aug 3, 2016 · 54b9fe9 · 54b9fe9
1 parent 04e415f
commit 54b9fe9
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 12 deletions.
diff --git a/API.md b/API.md
@@ -672,6 +672,8 @@ UTF8::split('déjà', 2); // array('dé', 'jà')
 
 Get a binary representation of a specific string.
 
+INFO: opposite to UTF8::binary_to_str()
+
 ```php
 UTF8::str_to_binary('😃'); // '11110000100111111001100010000011'
 ```
@@ -681,9 +683,44 @@ UTF8::str_to_binary('😃'); // '11110000100111111001100010000011'
 Get a binary representation of a specific string.
 
 ```php
-UTF8::str_word_count('中文空白 öäü abc'); // 3
-UTF8::str_word_count('中文空白 öäü abc', 1); // array('中文空白', 'öäü', 'abc')
-UTF8::str_word_count('中文空白 öäü abc', 2); // array(0 => '中文空白', 5 => 'öäü', 9 => 'abc')
+// format: 0 -> return only word count (int)
+//
+UTF8::str_word_count('中文空白 öäü abc#c'); // 4
+UTF8::str_word_count('中文空白 öäü abc#c', 0, '#'); // 3
+
+// format: 1 -> return words (array) 
+//
+UTF8::str_word_count('中文空白 öäü abc#c', 1); // array('中文空白', 'öäü', 'abc', 'c')
+UTF8::str_word_count('中文空白 öäü abc#c', 1, '#'); // array('中文空白', 'öäü', 'abc#c')
+
+// format: 2 -> return words with offset (array) 
+//
+UTF8::str_word_count('中文空白 öäü ab#c', 2); // array(0 => '中文空白', 5 => 'öäü', 9 => 'abc', 13 => 'c')
+UTF8::str_word_count('中文空白 öäü ab#c', 2, '#'); // array(0 => '中文空白', 5 => 'öäü', 9 => 'abc#c')
+```
+
+##### strcasecmp(string $str1, string $str2) : int
+
+Case-insensitive string comparison: < 0 if str1 is less than str2; 
+                                    > 0 if str1 is greater than str2, 
+                                    0 if they are equal.
+
+INFO: Case-insensitive version of UTF8::strcmp()
+
+```php
+UTF8::strcasecmp("iñtërnâtiôn\nàlizætiøn", "Iñtërnâtiôn\nàlizætiøn"); // 0
+```
+
+##### strcmp(string $str1, string $str2) : int
+
+Case-insensitive string comparison: < 0 if str1 is less than str2; 
+                                    > 0 if str1 is greater than str2, 
+                                    0 if they are equal.
+
+INFO: Case-sensitive version of UTF8::strcasecmp()
+
+```php
+UTF8::strcmp("iñtërnâtiôn\nàlizætiøn", "iñtërnâtiôn\nàlizætiøn"); // 0
 ```
 
 ... TODO
diff --git a/src/voku/helper/UTF8.php b/src/voku/helper/UTF8.php
@@ -4952,7 +4952,7 @@ public static function str_transliterate($str, $unknown = '?')
    * @param int    $format <strong>0</strong> => return a number of words<br />
    *                       <strong>1</strong> => return an array of words<br />
    *                       <strong>2</strong> => return an array of words with word-offset as key
-   * @param string $charlist Chars that contains to words and do not start a new word (default: "'", "’")
+   * @param string $charlist Additional chars that contains to words and do not start a new word (default: "'", "’")
    *
    * @return array|int The number of words in the string
    */
@@ -4996,21 +4996,23 @@ public static function str_word_count($str, $format = 0, $charlist = '')
    * @param string $str1
    * @param string $str2
    *
-   * @return int Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal.
+   * @return int <strong>&lt; 0</strong> if str1 is less than str2;<br />
+   *             <strong>&gt; 0</strong> if str1 is greater than str2,<br />
+   *             <strong>0</strong> if they are equal.
    */
   public static function strcasecmp($str1, $str2)
   {
     return self::strcmp(self::strtocasefold($str1), self::strtocasefold($str2));
   }
 
   /**
-   * String comparison.
+   * Case-sensitive string comparison.
    *
    * @param string $str1
    * @param string $str2
    *
-   * @return int  <strong>< 0</strong> if str1 is less than str2<br />
-   *              <strong>> 0</strong> if str1 is greater than str2<br />
+   * @return int  <strong>&lt; 0</strong> if str1 is less than str2<br />
+   *              <strong>&gt; 0</strong> if str1 is greater than str2<br />
    *              <strong>0</strong> if they are equal.
    */
   public static function strcmp($str1, $str2)
@@ -5237,8 +5239,8 @@ public static function strlen($str, $encoding = 'UTF-8', $cleanUtf8 = false)
    * @param string $str1
    * @param string $str2
    *
-   * @return int <strong>< 0</strong> if str1 is less than str2<br />
-   *             <strong>> 0</strong> if str1 is greater than str2<br />
+   * @return int <strong>&lt; 0</strong> if str1 is less than str2<br />
+   *             <strong>&gt; 0</strong> if str1 is greater than str2<br />
    *             <strong>0</strong> if they are equal
    */
   public static function strnatcasecmp($str1, $str2)

diff --git a/tests/Utf8GlobalTest.php b/tests/Utf8GlobalTest.php
@@ -3328,6 +3328,24 @@ public function testWordCount()
         ),
         UTF8::str_word_count('中文空白 foo öäü', 1)
     );
+    self::assertSame(3, UTF8::str_word_count('中文空白 foo öäü#s', 0, '#'));
+    self::assertSame(4, UTF8::str_word_count('中文空白 foo öäü#s', 0, ''));
+    self::assertSame(
+        array(
+            '中文空白',
+            'foo',
+            'öäü#s',
+        ),
+        UTF8::str_word_count('中文空白 foo öäü#s', 1, '#')
+    );
+    self::assertSame(
+        array(
+            0 => '中文空白',
+            5 => 'foo',
+            9 => 'öäü#s',
+        ),
+        UTF8::str_word_count('中文空白 foo öäü#s', 2, '#')
+    );
     self::assertSame(
         array(
             0 => '中文空白',

diff --git a/tests/Utf8StrcasecmpTest.php b/tests/Utf8StrcasecmpTest.php
@@ -12,48 +12,60 @@ public function test_compare_equal()
     $str_x = 'iñtërnâtiônàlizætiøn';
     $str_y = 'IÑTËRNÂTIÔNÀLIZÆTIØN';
     self::assertSame(0, u::strcasecmp($str_x, $str_y));
+    self::assertSame(1, u::strcmp($str_x, $str_y));
+
+    $str_x = 'IÑTËRNÂTIÔNÀLIZÆTIØN';
+    $str_y = 'IÑTËRNÂTIÔNÀLIZÆTIØN';
+    self::assertSame(0, u::strcasecmp($str_x, $str_y));
+    self::assertSame(0, u::strcmp($str_x, $str_y));
   }
 
   public function test_less()
   {
     $str_x = 'iñtërnâtiônàlizætiøn';
     $str_y = 'IÑTËRNÂTIÔÀLIZÆTIØN';
     self::assertTrue(u::strcasecmp($str_x, $str_y) > 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) > 0);
   }
 
   public function test_greater()
   {
     $str_x = 'iñtërnâtiôàlizætiøn';
     $str_y = 'IÑTËRNÂTIÔNÀLIZÆTIØN';
     self::assertTrue(u::strcasecmp($str_x, $str_y) < 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) > 0);
   }
 
   public function test_empty_x()
   {
     $str_x = '';
     $str_y = 'IÑTËRNÂTIÔNÀLIZÆTIØN';
     self::assertTrue(u::strcasecmp($str_x, $str_y) < 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) < 0);
   }
 
   public function test_empty_y()
   {
     $str_x = 'iñtërnâtiôàlizætiøn';
     $str_y = '';
     self::assertTrue(u::strcasecmp($str_x, $str_y) > 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) > 0);
   }
 
   public function test_empty_both()
   {
     $str_x = '';
     $str_y = '';
-    self::assertTrue(u::strcasecmp($str_x, $str_y) == 0);
+    self::assertTrue(u::strcasecmp($str_x, $str_y) === 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) === 0);
   }
 
   public function test_linefeed()
   {
     $str_x = "iñtërnâtiôn\nàlizætiøn";
     $str_y = "IÑTËRNÂTIÔN\nÀLIZÆTIØN";
-    self::assertTrue(u::strcasecmp($str_x, $str_y) == 0);
+    self::assertTrue(u::strcasecmp($str_x, $str_y) === 0);
+    self::assertTrue(u::strcmp($str_x, $str_y) === 1);
   }
 
 }