From: Kevin Day <thekevinday@gmail.com>
Date: Wed, 5 Apr 2017 02:52:23 +0000 (-0500)
Subject: Update: improve return values used in c_base_utf8 class functions (and related)
X-Git-Url: https://git.kevux.org/?a=commitdiff_plain;h=d729da83294f82cd6d82e216c3eb39a0e204c7fa;p=koopa

Update: improve return values used in c_base_utf8 class functions (and related)

I believe I was returning TRUE/FALSE types out of habit and for consistency.
For string processing functions, it makes far more sense to always return a c_base_return_string.
This simplifies the code the caller has to write.

The caller can still identify errors using the c_base_return::s_has_error() function.
The caller need only to call ->get_value_exact() if they do not care whether an error occured.
This will always return a string (and on error, it returns an empty string).
---

diff --git a/common/base/classes/base_http.php b/common/base/classes/base_http.php
index d6684c9..aeb97b9 100644
--- a/common/base/classes/base_http.php
+++ b/common/base/classes/base_http.php
@@ -4954,7 +4954,7 @@ class c_base_http extends c_base_rfc_string {
           }
           else {
             $c['language'] = $id->get_value_exact();
-            $this->request[self::REQUEST_ACCEPT_LANGUAGE]['data']['weight'][$weight][$c['language']] = (string) c_base_utf8::s_lowercase($c['choice'])->get_value();
+            $this->request[self::REQUEST_ACCEPT_LANGUAGE]['data']['weight'][$weight][$c['language']] = c_base_utf8::s_lowercase($c['choice'])->get_value_exact();
             unset($c['choice']);
           }
         }
@@ -5009,7 +5009,7 @@ class c_base_http extends c_base_rfc_string {
       // convert the known values into integers for improved processing.
       foreach ($this->request[self::REQUEST_ACCEPT_ENCODING]['data']['choices'] as $weight => &$choice) {
         foreach ($choice as $key => &$c) {
-          $lowercase = (string) c_base_utf8::s_lowercase($c['choice'])->get_value();
+          $lowercase = c_base_utf8::s_lowercase($c['choice'])->get_value_exact();
           if ($lowercase == 'chunked') {
             $c['encoding'] = self::ENCODING_CHUNKED;
             $this->request[self::REQUEST_ACCEPT_ENCODING]['data']['weight'][$weight][self::ENCODING_CHUNKED] = $lowercase;
@@ -5120,7 +5120,7 @@ class c_base_http extends c_base_rfc_string {
       // convert the known values into integers for improved processing.
       foreach ($this->request[self::REQUEST_ACCEPT_CHARSET]['data']['choices'] as $weight => &$choice) {
         foreach ($choice as $key => &$c) {
-          $lowercase = (string) c_base_utf8::s_lowercase($c['choice'])->get_value();
+          $lowercase = c_base_utf8::s_lowercase($c['choice'])->get_value_exact();
           if ($lowercase == 'ascii') {
             $c['charset'] = c_base_charset::ASCII;
             $this->request[self::REQUEST_ACCEPT_CHARSET]['data']['weight'][$weight][c_base_charset::ASCII] = $lowercase;
@@ -5274,7 +5274,7 @@ class c_base_http extends c_base_rfc_string {
    * @see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Request-Method
    */
   private function p_load_request_access_control_request_method() {
-    $method_string = (string) c_base_utf8::s_lowercase($this->headers['access_control_request_method'])->get_value();
+    $method_string = c_base_utf8::s_lowercase($this->headers['access_control_request_method'])->get_value_exact();
     $method_string = str_replace(' ', '', $method_string);
 
     $methods = explode(',', $method_string);
@@ -5454,7 +5454,7 @@ class c_base_http extends c_base_rfc_string {
 
     $parts = mb_split(', ', $cache_control);
     foreach ($parts as $part) {
-      $cleaned_up = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $part))->get_value();
+      $cleaned_up = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $part))->get_value_exact();
       if ($cleaned_up == 'no-cache') {
         $this->request[self::REQUEST_CACHE_CONTROL]['defined'] = TRUE;
         $this->request[self::REQUEST_CACHE_CONTROL]['data']['methods'][SELF::CACHE_CONTROL_NO_CACHE] = SELF::CACHE_CONTROL_NO_CACHE;
@@ -5563,7 +5563,7 @@ class c_base_http extends c_base_rfc_string {
       return;
     }
 
-    $cleaned_up = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $pragma))->get_value();
+    $cleaned_up = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $pragma))->get_value_exact();
     if ($cleaned_up == 'no-cache') {
       $this->request[self::REQUEST_CACHE_CONTROL]['defined'] = TRUE;
       $this->request[self::REQUEST_CACHE_CONTROL]['data'][SELF::CACHE_CONTROL_NO_CACHE] = SELF::CACHE_CONTROL_NO_CACHE;
@@ -5655,7 +5655,7 @@ class c_base_http extends c_base_rfc_string {
     }
 
     $content_type_parts = mb_split(';', $content_type);
-    $content_type_part = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $content_type_parts[0]))->get_value();
+    $content_type_part = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $content_type_parts[0]))->get_value_exact();
 
     $this->request[self::REQUEST_CONTENT_TYPE]['defined'] = TRUE;
     $this->request[self::REQUEST_CONTENT_TYPE]['data'] = $content_type_part;
@@ -6142,7 +6142,7 @@ class c_base_http extends c_base_rfc_string {
       // convert the known values into integers for improved processing.
       foreach ($this->request[self::REQUEST_TE]['data']['choices'] as $weight => &$choice) {
         foreach ($choice as $key => &$c) {
-          $lowercase = (string) c_base_utf8::s_lowercase($c['choice'])->get_value();
+          $lowercase = c_base_utf8::s_lowercase($c['choice'])->get_value_exact();
           if ($c['choice'] == 'compress') {
             $c['encoding'] = self::ENCODING_COMPRESS;
           }
@@ -6592,9 +6592,9 @@ class c_base_http extends c_base_rfc_string {
     $this->request[$key]['defined'] = TRUE;
     $this->request[$key]['invalid'] = FALSE;
 
-    $this->request[$key]['data'] = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $raw))->get_value();
+    $this->request[$key]['data'] = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $raw))->get_value_exact();
     if (!is_null($max_length)) {
-      $this->request[$key]['data'] = c_base_utf8::s_substring($this->request[$key]['data'], 0, $max_length);
+      $this->request[$key]['data'] = c_base_utf8::s_substring($this->request[$key]['data'], 0, $max_length)->get_value_exact();
     }
     unset($raw);
   }
@@ -6622,9 +6622,9 @@ class c_base_http extends c_base_rfc_string {
     $this->request[$key]['invalid'] = FALSE;
 
 
-    $this->request[$key]['data'][$field] = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $raw))->get_value();
+    $this->request[$key]['data'][$field] = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $raw))->get_value_exact();
     if (!is_null($max_length)) {
-      $this->request[$key]['data'][$field] = c_base_utf8::s_substring($this->request[$key]['data'][$field], 0, $max_length);
+      $this->request[$key]['data'][$field] = c_base_utf8::s_substring($this->request[$key]['data'][$field], 0, $max_length)->get_value_exact();
     }
     unset($raw);
   }
@@ -6654,10 +6654,10 @@ class c_base_http extends c_base_rfc_string {
       return FALSE;
     }
 
-    $raw = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $original))->get_value();
+    $raw = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $original))->get_value_exact();
 
     // rfc5322 is the preferred/recommended format.
-    $rfc5322 = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_5322, $timestamp)))->get_value();
+    $rfc5322 = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_5322, $timestamp)))->get_value_exact();
     if ($raw == $rfc5322) {
       unset($raw);
       unset($timestamp);
@@ -6666,7 +6666,7 @@ class c_base_http extends c_base_rfc_string {
     }
     unset($rfc5322);
 
-    $rfc1123 = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_1123, $timestamp)))->get_value();
+    $rfc1123 = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_1123, $timestamp)))->get_value_exact();
     if ($raw == $rfc1123) {
       unset($raw);
       unset($timestamp);
@@ -6675,7 +6675,7 @@ class c_base_http extends c_base_rfc_string {
     }
     unset($rfc1123);
 
-    $rfc850 = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_850, $timestamp)))->get_value();
+    $rfc850 = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', date(self::TIMESTAMP_RFC_850, $timestamp)))->get_value_exact();
     if ($raw == $rfc850) {
       unset($raw);
       unset($timestamp);
@@ -6702,10 +6702,10 @@ class c_base_http extends c_base_rfc_string {
   private function p_process_accept_parts_sub($super, &$value, &$priority) {
     $parts_sub = mb_split(self::DELIMITER_ACCEPT_SUB, $super);
 
-    $part_sub_value = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $parts_sub[0]))->get_value();
+    $part_sub_value = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $parts_sub[0]))->get_value_exact();
     $part_sub_priority = NULL;
     if (count($parts_sub) > 1) {
-      $part_sub_priority = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $parts_sub[1]))->get_value();
+      $part_sub_priority = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $parts_sub[1]))->get_value_exact();
     }
 
     if (self::p_length_string($part_sub_value) > 2) {
@@ -7041,8 +7041,8 @@ class c_base_http extends c_base_rfc_string {
       }
 
       if (isset($pieces[1])) {
-        $lower_piece_1 = (string) preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value();
-        $lower_piece_2 = (string) preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[1]))->get_value();
+        $lower_piece_1 = preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value_exact();
+        $lower_piece_2 = preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[1]))->get_value_exact();
 
         if ($lower_piece_1 == 'trident') {
           $result['engine_name_machine'] = 'trident';
@@ -7067,7 +7067,7 @@ class c_base_http extends c_base_rfc_string {
         unset($lower_piece_2);
       }
       elseif (isset($pieces[0])) {
-        $lower_cased = (string) c_base_utf8::s_lowercase($pieces[0])->get_value();
+        $lower_cased = c_base_utf8::s_lowercase($pieces[0])->get_value_exact();
         $lower_piece_1 = preg_replace('/(^\s+)|(\s+$)/us', '', $lower_cased);
         unset($lower_cased);
 
@@ -7120,11 +7120,11 @@ class c_base_http extends c_base_rfc_string {
           }
 
           if (isset($pieces[1])) {
-            $lower_cased = (string) c_base_utf8::s_lowercase($pieces[0])->get_value();
+            $lower_cased = c_base_utf8::s_lowercase($pieces[0])->get_value_exact();
             $lower_piece_1 = preg_replace('/(^\s+)|(\s+$)/us', '', $lower_cased);
             unset($lower_cased);
 
-            $lower_cased = (string) c_base_utf8::s_lowercase($pieces[1])->get_value();
+            $lower_cased = c_base_utf8::s_lowercase($pieces[1])->get_value_exact();
             $lower_piece_2 = preg_replace('/(^\s+)|(\s+$)/us', '', $lower_cased);
             unset($lower_cased);
 
@@ -7271,7 +7271,7 @@ class c_base_http extends c_base_rfc_string {
             unset($lower_piece_2);
           }
           elseif (isset($pieces[0])) {
-            $lower_cased = (string) c_base_utf8::s_lowercase($pieces[0])->get_value();
+            $lower_cased = c_base_utf8::s_lowercase($pieces[0])->get_value_exact();
             $lower_piece_1 = preg_replace('/(^\s+)|(\s+$)/us', '', $lower_cased);
             unset($lower_cased);
 
@@ -7376,8 +7376,8 @@ class c_base_http extends c_base_rfc_string {
         $pieces = mb_split('/', $agent_matches[0]);
         $total_pieces = count($pieces);
         if ($total_pieces == 2) {
-          $lower_piece_1 = (string) preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value();
-          $lower_piece_2 = (string) preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[1]))->get_value();
+          $lower_piece_1 = preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value_exact();
+          $lower_piece_2 = preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[1]))->get_value_exact();
 
           if ($lower_piece_1 == 'curl') {
             $result['engine_name_machine'] = 'curl';
@@ -7444,7 +7444,7 @@ class c_base_http extends c_base_rfc_string {
           unset($lower_piece_2);
         }
         elseif ($total_pieces == 1) {
-          $lower_piece = (string) preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value();
+          $lower_piece = preg_replace('/(^\s+)|(\s+$)/us', '', c_base_utf8::s_lowercase($pieces[0]))->get_value_exact();
 
           if ($lower_piece == 'links') {
             $result['engine_name_machine'] = 'links';
@@ -7494,7 +7494,7 @@ class c_base_http extends c_base_rfc_string {
       'invalid' => FALSE,
     );
 
-    $fixed_checksum = (string) c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $checksum))->get_value();
+    $fixed_checksum = c_base_utf8::s_lowercase(preg_replace('/(^\s+)|(\s+$)/us', '', $checksum))->get_value_exact();
     if (empty($fixed_checksum)) {
       $result['invalid'] = TRUE;
       unset($fixed_checksum);
@@ -7653,7 +7653,7 @@ class c_base_http extends c_base_rfc_string {
       'invalid' => FALSE,
     );
 
-    $fixed_checksum = (string) c_base_utf8::s_lowercase(preg_replace("/(^( |\t)+)|(( |\t)+$)/us", '', $checksum_headers))->get_value();
+    $fixed_checksum = c_base_utf8::s_lowercase(preg_replace("/(^( |\t)+)|(( |\t)+$)/us", '', $checksum_headers))->get_value_exact();
     if (empty($fixed_checksum)) {
       $result['invalid'] = TRUE;
       unset($fixed_checksum);
@@ -7722,13 +7722,7 @@ class c_base_http extends c_base_rfc_string {
    *   0 is returned on any error.
    */
   private function p_length_string($string) {
-    $length = c_base_utf8::s_length_string($string);
-    if ($length instanceof c_base_return_false) {
-      unset($length);
-      return 0;
-    }
-
-    return $length->get_value_exact();
+    return c_base_utf8::s_length_string($string)->get_value_exact();
   }
 
   /**
@@ -7756,7 +7750,7 @@ class c_base_http extends c_base_rfc_string {
       foreach ($all_headers as $key => $value) {
         // break the header name so that it is consistent until such time that PHP stops clobbering the header names.
         $broken = preg_replace('/-/u', '_', $key);
-        $broken = (string) c_base_utf8::s_lowercase($broken)->get_value();
+        $broken = c_base_utf8::s_lowercase($broken)->get_value_exact();
         $this->headers[$broken] = $value;
         unset($broken);
       }
@@ -7768,13 +7762,13 @@ class c_base_http extends c_base_rfc_string {
       // non-apache, or calling php from command line.
       if (isset($_SERVER) && is_array($_SERVER) && !empty($_SERVER)) {
         foreach ($_SERVER as $key => $value) {
-          $part = (string) c_base_utf8::s_lowercase(c_base_utf8::s_substring($key, 0, 5))->get_value();
+          $part = c_base_utf8::s_lowercase(c_base_utf8::s_substring($key, 0, 5))->get_value_exact();
 
           if ($part != 'http_') {
             continue;
           }
 
-          $part = (string) c_base_utf8::s_lowercase(c_base_utf8::s_substring($key, 5))->get_value();
+          $part = c_base_utf8::s_lowercase(c_base_utf8::s_substring($key, 5))->get_value_exact();
           $this->headers[$part] = $value;
         }
         unset($part);
@@ -8008,7 +8002,7 @@ class c_base_http extends c_base_rfc_string {
    */
   private function p_prepare_token($token_name, $lower_case = TRUE) {
     if ($lower_case) {
-      $lower_cased = (string) c_base_utf8::s_lowercase($token_name)->get_value();
+      $lower_cased = c_base_utf8::s_lowercase($token_name)->get_value_exact();
       $trimmed = preg_replace('/(^\s+)|(\s+$)/us', '', $lower_cased);
       unset($lower_cased);
 
diff --git a/common/base/classes/base_rfc_string.php b/common/base/classes/base_rfc_string.php
index be25771..40542c5 100644
--- a/common/base/classes/base_rfc_string.php
+++ b/common/base/classes/base_rfc_string.php
@@ -101,7 +101,7 @@ abstract class c_base_rfc_string extends c_base_rfc_char {
     unset($ordinals);
 
     $characters = c_base_utf8::s_ordinals_to_string_array($result['ordinals']);
-    if ($characters instanceof c_base_return_false) {
+    if (c_base_return::s_has_error($characters)) {
       unset($characters);
       $result['invalid'] = TRUE;
       return $result;
diff --git a/common/base/classes/base_utf8.php b/common/base/classes/base_utf8.php
index 28d312b..561f005 100644
--- a/common/base/classes/base_utf8.php
+++ b/common/base/classes/base_utf8.php
@@ -143,16 +143,16 @@ class c_base_utf8 {
    * @param string $text
    *   The string for which to find the character length.
    *
-   * @return c_base_return_int|c_base_return_status
+   * @return c_base_return_int
    *   Length of the Unicode String.
-   *   FALSE with error bit set is returned on error.
+   *   0 with error bit set is returned on error.
    *
    * @see: mb_strlen()
    */
   public static function s_length_string($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(0, 'c_base_return_int', $error);
     }
 
     $length = self::p_s_length_string($text);
@@ -160,7 +160,7 @@ class c_base_utf8 {
       unset($length);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_length_string', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(0, 'c_base_return_int', $error);
     }
 
     return c_base_return_int::s_new($length);
@@ -175,19 +175,19 @@ class c_base_utf8 {
    *   (optional) When TRUE, the UTF_8 BOM character is removed.
    *   When FALSE, no action related to the BOM character is performed.
    *
-   * @return c_base_return_string|c_base_return_status
+   * @return c_base_return_string
    *   Clean UTF-8 encoded string.
-   *   FALSE with error bit set is returned on error.
+   *   An empty string with error bit set is returned on error.
    */
   public static function s_clean($text, $remove_bom = FALSE) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     if (!is_bool($remove_bom)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'remove_bom', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $sanitized = self::p_s_clean($text);
@@ -195,7 +195,7 @@ class c_base_utf8 {
       unset($sanitized);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_clean', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new($sanitized);
@@ -209,19 +209,19 @@ class c_base_utf8 {
    * @param int $split_length
    *   Max character length of each array element.
    *
-   * @return c_base_return_array|c_base_return_status
+   * @return c_base_return_array
    *   An array containing chunks of the string.
-   *   FALSE with error bit set is returned on error.
+   *   An empty string with error bit set is returned on error.
    */
   public static function s_split($text, $split_length = 1) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     if (!is_int($split_length)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'split_length', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $split = self::p_s_split($text, $split_length);
@@ -229,7 +229,7 @@ class c_base_utf8 {
       unset($split);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_split', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_array::s_new($split);
@@ -241,14 +241,14 @@ class c_base_utf8 {
    * @param string $text
    *   The original Unicode string.
    *
-   * @return c_base_return_array|c_base_return_status
+   * @return c_base_return_array
    *   An array of byte lengths of each character.
-   *   FALSE with error bit set is returned on error.
+   *   An empty array with error bit set is returned on error.
    */
   public static function s_character_size_list($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(array(), 'c_base_return_array', $error);
     }
 
     $size_list = self::p_s_character_size_list($text);
@@ -256,7 +256,7 @@ class c_base_utf8 {
       unset($size_list);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_character_size_list', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(array(), 'c_base_return_array', $error);
     }
 
     return c_base_return_array::s_new($size_list);
@@ -268,16 +268,16 @@ class c_base_utf8 {
    * @param string $text
    *   The original Unicode string.
    *
-   * @return c_base_return_int|c_base_return_status
+   * @return c_base_return_int
    *   An integer representing the max character width found within the passed string.
-   *   FALSE with error bit set is returned on error.
+   *   0 with error bit set is returned on error.
    *
    * @see: p_s_character_size_list()
    */
   public static function s_character_max_width($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(0, 'c_base_return_int', $error);
     }
 
     $size_list = self::p_s_character_size_list($text);
@@ -285,7 +285,7 @@ class c_base_utf8 {
       unset($size_list);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_character_size_list', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(0, 'c_base_return_int', $error);
     }
 
     return c_base_return_int::s_new(max($size_list));
@@ -297,16 +297,16 @@ class c_base_utf8 {
    * @param string $character
    *   The Unicode character to be encoded as numbered entity
    *
-   * @return c_base_return_string|c_base_return_status
+   * @return c_base_return_string
    *   HTML numbered entity.
-   *   FALSE with error bit set is returned on error.
+   *   An empty string error bit set is returned on error.
    *
    * @see: p_s_encode_html_character()
    */
   public static function s_encode_html_character($character) {
     if (!is_string($character)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'character', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $encoded = self::p_s_encode_html_character($character);
@@ -314,7 +314,7 @@ class c_base_utf8 {
       unset($encoded);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_encode_html_character', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new($encoded);
@@ -326,14 +326,14 @@ class c_base_utf8 {
    * @param string $text
    *   The Unicode string to be encoded as numbered entities.
    *
-   * @return c_base_return_string|c_base_return_status
+   * @return c_base_return_string
    *   HTML numbered entities.
-   *   FALSE with error bit set is returned on error.
+   *   An empty string error bit set is returned on error.
    */
   public static function s_encode_html($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $split = self::p_s_split($text);
@@ -341,7 +341,7 @@ class c_base_utf8 {
       unset($split);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_split', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $new_array = array();
@@ -373,22 +373,26 @@ class c_base_utf8 {
    *   (optional) The length of the substring.
    *   If NULL, then the length is PHP_INT_MAX.
    *
+   * @return c_base_return_string
+   *   A substring of the specified string.
+   *   An empty string error bit set is returned on error.
+   *
    * @see: mb_substr()
    */
   public static function s_substring($text, $start = 0, $length = NULL) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     if (!is_int($start)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'start', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     if (!is_null($length) && !is_int($length)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'length', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new(self::p_s_substring($text, $start, $length));
@@ -402,12 +406,16 @@ class c_base_utf8 {
    * @param string $text
    *   The string to transform to lowercase from.
    *
+   * @return c_base_return_string
+   *   A string with its characters all in lowercase.
+   *   An empty string error bit set is returned on error.
+   *
    * @see: mb_strtolower()
    */
   public static function s_lowercase($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new(self::p_s_lowercase($text));
@@ -421,12 +429,16 @@ class c_base_utf8 {
    * @param string $text
    *   The string to transform to lowercase from.
    *
+   * @return c_base_return_string
+   *   A string with its characters all in uppercase.
+   *   An empty string error bit set is returned on error.
+   *
    * @see: mb_strtoupper()
    */
   public static function s_uppercase($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new(self::p_s_uppercase($text));
@@ -536,14 +548,14 @@ class c_base_utf8 {
    * @param string $text
    *   The input string.
    *
-   * @return c_base_return_string|c_base_return_status
+   * @return c_base_return_string
    *   The string with characters in the reverse sequence.
-   *   FALSE with error bit set is returned on error.
+   *   An empty string error bit set is returned on error.
    */
   public static function s_reverse($text) {
     if (!is_string($text)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'text', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     $split = self::p_s_split($text);
@@ -551,7 +563,7 @@ class c_base_utf8 {
       unset($split);
 
       $error = c_base_error::s_log(NULL, array('arguments' => array(':operation_name' => 'self::p_s_split', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::OPERATION_FAILURE);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value('', 'c_base_return_string', $error);
     }
 
     return c_base_return_string::s_new(implode(array_reverse($split)));
@@ -676,14 +688,15 @@ class c_base_utf8 {
    * @param array $ordinals
    *   An array of ordinals.
    *
-   * @return c_base_return_array|c_base_return_status
+   * @return c_base_return_array
    *   An array of characters represnting the ordinals array.
-   *   FALSE with error bit set is returned on error.
+   *   An empty array with error bit set is returned on error.
+   *   A partially populate array with error bit set is returned on error of individual characters.
    */
   public static function s_ordinals_to_string_array($ordinals) {
     if (!is_array($ordinals)) {
       $error = c_base_error::s_log(NULL, array('arguments' => array(':argument_name' => 'ordinals', ':function_name' => __CLASS__ . '->' . __FUNCTION__)), i_base_error_messages::INVALID_ARGUMENT);
-      return c_base_return_error::s_false($error);
+      return c_base_return_error::s_value(array(), 'c_base_return_array', $error);
     }
 
     $errors = array();
@@ -807,7 +820,7 @@ class c_base_utf8 {
     }
 
     if ($offset || $length) {
-      $haystack = s_substring($haystack, $offset, $length);
+      $haystack = self::s_substring($haystack, $offset, $length)->get_value_exact();
     }
 
     if (is_null($length)) {