Cleanup phpdoc comments
[civicrm-core.git] / CRM / Utils / String.php
index 4ba11f1942fd812385e4fa4dffb12346d7529dcf..c435cd7a7b739a0acb784595c66725356bc64606 100644 (file)
@@ -1,9 +1,9 @@
 <?php
 /*
  +--------------------------------------------------------------------+
- | CiviCRM version 4.4                                                |
+ | CiviCRM version 4.5                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2013                                |
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -28,7 +28,7 @@
 /**
  *
  * @package CRM
- * @copyright CiviCRM LLC (c) 2004-2013
+ * @copyright CiviCRM LLC (c) 2004-2014
  * $Id$
  *
  */
@@ -53,6 +53,8 @@ class CRM_Utils_String {
    *
    * @param  name    Name of the string
    *
+   * @param int $maxLength
+   *
    * @return string  An equivalent variable name
    *
    * @access public
@@ -73,7 +75,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * given a string, replace all non alpha numeric characters and
+   * Given a string, replace all non alpha numeric characters and
    * spaces with the replacement character
    *
    * @param string $name the name to be worked on
@@ -100,6 +102,26 @@ class CRM_Utils_String {
     }
   }
 
+  /**
+   * Convert possibly underscore separated words to camel case with special handling for 'UF'
+   * e.g
+   * membership_payment returns MembershipPayment
+   * @param string $string
+   *
+   * @return string string
+   */
+  static function convertStringToCamel($string) {
+    $fragments = explode('_', $string);
+    foreach ($fragments as & $fragment) {
+      $fragment = ucfirst($fragment);
+    }
+    // Special case: UFGroup, UFJoin, UFMatch, UFField
+    if ($fragments[0] === 'Uf') {
+      $fragments[0] = 'UF';
+    }
+    return implode('', $fragments);
+  }
+
   /**
    *
    * Takes a variable name and munges it randomly into another variable name
@@ -117,11 +139,11 @@ class CRM_Utils_String {
   }
 
   /**
-   * takes a string and returns the last tuple of the string.
+   * Takes a string and returns the last tuple of the string.
    * useful while converting file names to class names etc
    *
    * @param string $string the input string
-   * @param char   $char   the character used to demarcate the componets
+   * @param \char|string $char $char   the character used to demarcate the componets
    *
    * @access public
    *
@@ -139,7 +161,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * appends a name to a string and seperated by delimiter.
+   * Appends a name to a string and seperated by delimiter.
    * does the right thing for an empty string
    *
    * @param string $str   the string to be appended to
@@ -179,7 +201,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * determine if the string is composed only of ascii characters
+   * Determine if the string is composed only of ascii characters
    *
    * @param string  $str input string
    * @param boolean $utf8 attempt utf8 match on failure (default yes)
@@ -221,7 +243,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * determine the string replacements for redaction
+   * Determine the string replacements for redaction
    * on the basis of the regular expressions
    *
    * @param string $str        input string
@@ -263,6 +285,12 @@ class CRM_Utils_String {
     return CRM_Core_DAO::$_nullArray;
   }
 
+  /**
+   * @param $str
+   * @param $stringRules
+   *
+   * @return mixed
+   */
   static function redaction($str, $stringRules) {
     //redact the strings
     if (!empty($stringRules)) {
@@ -305,7 +333,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * determine if two href's are equivalent (fuzzy match)
+   * Determine if two href's are equivalent (fuzzy match)
    *
    * @param string $url1 the first url to be matched
    * @param string $url2 the second url to be matched against
@@ -330,7 +358,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * Function to extract variable values
+   * Extract variable values
    *
    * @param  mix $query this is basically url
    *
@@ -355,7 +383,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * translate a true/false/yes/no string to a 0 or 1 value
+   * Translate a true/false/yes/no string to a 0 or 1 value
    *
    * @param string $str  the string to be translated
    *
@@ -375,7 +403,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
+   * Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
    *
    * @param string $str  the string to be translated
    *
@@ -417,6 +445,10 @@ class CRM_Utils_String {
     return $text;
   }
 
+  /**
+   * @param $string
+   * @param array $params
+   */
   static function extractName($string, &$params) {
     $name = trim($string);
     if (empty($name)) {
@@ -467,6 +499,11 @@ class CRM_Utils_String {
     }
   }
 
+  /**
+   * @param $string
+   *
+   * @return array
+   */
   static function &makeArray($string) {
     $string = trim($string);
 
@@ -481,19 +518,6 @@ class CRM_Utils_String {
     return $result;
   }
 
-  /**
-   * Function to add include files needed for jquery
-   *
-   * This appears to be used in cases where the normal html-header
-   * provided by CRM_Core_Resources can't be used (e.g. when outputting in
-   * "print" mode, the execution will short-circuit without allowing the
-   * CMS to output JS/CSS tags).
-   */
-  static function addJqueryFiles(&$html) {
-    CRM_Core_Resources::singleton()->addCoreResources('html-header');
-    return CRM_Core_Region::instance('html-header')->render('', FALSE) . $html;
-  }
-
   /**
    * Given an ezComponents-parsed representation of
    * a text with alternatives return only the first one
@@ -517,7 +541,7 @@ class CRM_Utils_String {
   }
 
   /**
-   * strip leading, trailing, double spaces from string
+   * Strip leading, trailing, double spaces from string
    * used for postal/greeting/addressee
    *
    * @param string  $string input string to be cleaned
@@ -607,6 +631,8 @@ class CRM_Utils_String {
    *
    * @param string $string
    * @param int $maxLen
+   *
+   * @return string
    */
   static function ellipsify($string, $maxLen) {
     $len = strlen($string);
@@ -639,7 +665,10 @@ class CRM_Utils_String {
    * "admin foo" => array(NULL,"admin foo")
    * "cms:admin foo" => array("cms", "admin foo")
    *
+   * @param $delim
    * @param string $string e.g. "view all contacts". Syntax: "[prefix:]name"
+   * @param null $defaultPrefix
+   *
    * @return array (0 => string|NULL $prefix, 1 => string $value)
    */
   public static function parsePrefix($delim, $string, $defaultPrefix = NULL) {
@@ -652,6 +681,62 @@ class CRM_Utils_String {
     }
   }
 
+  /**
+   * This function will mask part of the the user portion of an Email address (everything before the @)
+   *
+   * @param string $email the email address to be masked
+   * @param string $maskChar the character used for masking
+   * @param integer $percent the percentage of the user portion to be masked
+   *
+   * @return string returns the masked Email address
+   */
+  public static function maskEmail($email, $maskChar= '*', $percent=50) {
+    list($user, $domain) = preg_split("/@/", $email);
+    $len = strlen($user);
+    $maskCount = floor($len * $percent /100);
+    $offset = floor(($len - $maskCount) / 2);
+
+    $masked = substr($user, 0, $offset)
+      .str_repeat($maskChar, $maskCount)
+      .substr($user, $maskCount + $offset);
+
+    return($masked.'@'.$domain);
+  }
+
+  /**
+   * This function compares two strings
+   *
+   * @param string $strOne string one
+   * @param string $strTwo string two
+   * @param boolean $case boolean indicating whether you want the comparison to be case sensitive or not
+   *
+   * @return boolean TRUE (string are identical); FALSE (strings are not identical)
+   */
+  public static function compareStr($strOne, $strTwo, $case) {
+    if ($case == TRUE) {
+      // Convert to lowercase and trim white spaces
+      if (strtolower(trim($strOne)) == strtolower(trim($strTwo))) {
+        // yes - they are identical
+        return TRUE;
+      }
+      else {
+        // not identical
+        return FALSE;
+      }
+    }
+    if ($case == FALSE) {
+      // Trim white spaces
+      if (trim($strOne) == trim($strTwo)) {
+        // yes - they are identical
+        return TRUE;
+      }
+      else {
+        // not identical
+        return FALSE;
+      }
+    }
+  }
+
   /**
    * Many parts of the codebase have a convention of internally passing around
    * HTML-encoded URLs. This effectively means that "&" is replaced by "&amp;"