From 31310ecde095e8697e96868adf549e7260dedb36 Mon Sep 17 00:00:00 2001 From: tokul Date: Sun, 3 Jul 2005 09:55:10 +0000 Subject: [PATCH] documenting functions and adding some sq_mb_list_encodings updates git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@9702 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- functions/strings.php | 114 +++++++++++++++++++++++++++++------------- 1 file changed, 79 insertions(+), 35 deletions(-) diff --git a/functions/strings.php b/functions/strings.php index dca58dec..22f61f1b 100644 --- a/functions/strings.php +++ b/functions/strings.php @@ -13,6 +13,9 @@ * @package squirrelmail */ +/** @ignore */ +if (!defined('SM_PATH')) define('SM_PATH','../'); + /** * SquirrelMail version number -- DO NOT CHANGE */ @@ -31,17 +34,17 @@ $SQM_INTERNAL_VERSION = array(1,5,1); * referenced by the include of global.php, etc. before it's defined. * For that reason, bring in global.php AFTER we define the version strings. */ -require_once(SM_PATH . 'functions/global.php'); +include_once(SM_PATH . 'functions/global.php'); /** * Appends citation markers to the string. * Also appends a trailing space. * * @author Justus Pendleton - * - * @param string str The string to append to - * @param int citeLevel the number of markers to append + * @param string $str The string to append to + * @param int $citeLevel the number of markers to append * @return null + * @since 1.5.1 */ function sqMakeCite (&$str, $citeLevel) { for ($i = 0; $i < $citeLevel; $i++) { @@ -57,11 +60,11 @@ function sqMakeCite (&$str, $citeLevel) { * markers to the newline as necessary. * * @author Justus Pendleton - * - * @param string str the string to make a newline in - * @param int citeLevel the citation level the newline is at - * @param int column starting column of the newline + * @param string $str the string to make a newline in + * @param int $citeLevel the citation level the newline is at + * @param int $column starting column of the newline * @return null + * @since 1.5.1 */ function sqMakeNewLine (&$str, $citeLevel, &$column) { $str .= "\n"; @@ -92,6 +95,7 @@ function sqMakeNewLine (&$str, $citeLevel, &$column) { * * @param string $string tested string * @return bool true when only whitespace symbols are present in test string + * @since 1.5.1 */ function sm_ctype_space($string) { if ( preg_match('/^[\x09-\x0D]|^\x20/', $string) || $string=='') { @@ -108,10 +112,10 @@ function sm_ctype_space($string) { * bit smarter and when and how to wrap. * * @author Justus Pendleton - * - * @param string body the entire body of text - * @param int wrap the maximum line length + * @param string $body the entire body of text + * @param int $wrap the maximum line length * @return string the wrapped text + * @since 1.5.1 */ function &sqBodyWrap (&$body, $wrap) { //check for ctype support, and fake it if it doesn't exist @@ -351,10 +355,11 @@ function &sqBodyWrap (&$body, $wrap) { * Specifically, &#039; comes up as 5 characters instead of 1. * This should not add newlines to the end of lines. * - * @param string line the line of text to wrap, by ref - * @param int wrap the maximum line lenth - * @param string charset name of charset used in $line string. Available since v.1.5.1. + * @param string $line the line of text to wrap, by ref + * @param int $wrap the maximum line lenth + * @param string $charset name of charset used in $line string. Available since v.1.5.1. * @return void + * @since 1.0 */ function sqWordWrap(&$line, $wrap, $charset='') { global $languages, $squirrelmail_language; @@ -411,8 +416,9 @@ function sqWordWrap(&$line, $wrap, $charset='') { /** * Does the opposite of sqWordWrap() - * @param string body the text to un-wordwrap + * @param string $body the text to un-wordwrap * @return void + * @since 1.0 */ function sqUnWordWrap(&$body) { global $squirrelmail_language; @@ -456,6 +462,7 @@ function sqUnWordWrap(&$body) { * @param string haystack full mailbox name to search * @param string needle the mailbox separator character * @return string the last part of the mailbox name + * @since 1.0 */ function readShortMailboxName($haystack, $needle) { @@ -478,6 +485,7 @@ function readShortMailboxName($haystack, $needle) { * REQUEST_URI, or the PHP global PHP_SELF with QUERY_STRING added. * * @return string the complete url for this page + * @since 1.2.3 */ function php_self () { if ( sqgetGlobalVar('REQUEST_URI', $req_uri, SQ_SERVER) && !empty($req_uri) ) { @@ -511,6 +519,7 @@ function php_self () { * http://www.example.com/squirrelmail/ * * @return string the base url for this SquirrelMail installation + * @since 1.0 */ function get_location () { @@ -582,9 +591,10 @@ function get_location () { * stored in a cookie. The encryption key is generated by * OneTimePadCreate(); * - * @param string string the (password)string to encrypt - * @param string epad the encryption key + * @param string $string the (password)string to encrypt + * @param string $epad the encryption key * @return string the base64-encoded encrypted password + * @since 1.0 */ function OneTimePadEncrypt ($string, $epad) { $pad = base64_decode($epad); @@ -612,9 +622,10 @@ function OneTimePadEncrypt ($string, $epad) { * Decrypts a password from the cookie, encrypted by OneTimePadEncrypt. * This uses the encryption key that is stored in the session. * - * @param string string the string to decrypt - * @param string epad the encryption key from the session + * @param string $string the string to decrypt + * @param string $epad the encryption key from the session * @return string the decrypted password + * @since 1.0 */ function OneTimePadDecrypt ($string, $epad) { $pad = base64_decode($epad); @@ -645,8 +656,9 @@ function OneTimePadDecrypt ($string, $epad) { * appropriately. With strings, it is better to get them long. * Use md5() to lengthen smaller strings. * - * @param mixed val a value to seed the random number generator + * @param mixed $val a value to seed the random number generator. mixed = integer or string. * @return void + * @since 1.0 */ function sq_mt_seed($Val) { /* if mt_getrandmax() does not return a 2^n - 1 number, @@ -677,6 +689,7 @@ function sq_mt_seed($Val) { * the same 'random' numbers twice in one session. * * @return void + * @since 1.0 */ function sq_mt_randomize() { static $randomized; @@ -718,8 +731,10 @@ function sq_mt_randomize() { * Creates an encryption key for encrypting the password stored in the cookie. * The encryption key itself is stored in the session. * - * @param int length optional, length of the string to generate + * Pad must be longer or equal to encoded string length in 1.4.4/1.5.0 and older. + * @param int $length optional, length of the string to generate * @return string the encryption key + * @since 1.0 */ function OneTimePadCreate ($length=100) { sq_mt_randomize(); @@ -735,8 +750,9 @@ function OneTimePadCreate ($length=100) { /** * Returns a string showing the size of the message/attachment. * - * @param int bytes the filesize in bytes + * @param int $bytes the filesize in bytes * @return string the filesize in human readable format + * @since 1.0 */ function show_readable_size($bytes) { $bytes /= 1024; @@ -761,14 +777,15 @@ function show_readable_size($bytes) { /** * Generates a random string from the character set you pass in * - * @param int size the size of the string to generate - * @param string chars a string containing the characters to use - * @param int flags a flag to add a specific set to the characters to use: + * @param int $size the length of the string to generate + * @param string $chars a string containing the characters to use + * @param int $flags a flag to add a specific set to the characters to use: * Flags: * 1 = add lowercase a-z to $chars * 2 = add uppercase A-Z to $chars * 4 = add numbers 0-9 to $chars * @return string the random string + * @since 1.0 */ function GenerateRandomString($size, $chars, $flags = 0) { if ($flags & 0x1) { @@ -799,8 +816,9 @@ function GenerateRandomString($size, $chars, $flags = 0) { /** * Escapes special characters for use in IMAP commands. * - * @param string the string to escape + * @param string $str the string to escape * @return string the escaped string + * @since 1.0.3 */ function quoteimap($str) { return preg_replace("/([\"\\\\])/", "\\\\$1", $str); @@ -810,7 +828,8 @@ function quoteimap($str) { * Trims array * * Trims every element in the array, ie. remove the first char of each element - * @param array array the array to trim + * @param array $array the array to trim + * @since 1.2.0 */ function TrimArray(&$array) { foreach ($array as $k => $v) { @@ -833,9 +852,11 @@ function TrimArray(&$array) { * * Returns a link to the compose-page, taking in consideration * the compose_in_new and javascript settings. - * @param string url the URL to the compose page - * @param string text the link text, default "Compose" + * @param string $url the URL to the compose page + * @param string $text the link text, default "Compose" + * @param string $target (since 1.4.3) url target * @return string a link to the compose page + * @since 1.4.2 */ function makeComposeLink($url, $text = null, $target='') { global $compose_new_win,$javascript_on, $compose_width, $compose_height; @@ -875,7 +896,6 @@ function makeComposeLink($url, $text = null, $target='') { * The output is wrapped in <
> and <
> tags. * Since 1.4.2 accepts unlimited number of arguments. * @since 1.4.1 - * * @return void */ function sm_print_r() { @@ -906,6 +926,10 @@ function sm_print_r() { /** * version of fwrite which checks for failure + * @param resource $fp + * @param string $string + * @return number of written bytes. false on failure + * @since 1.4.3 */ function sq_fwrite($fp, $string) { // write to file @@ -936,6 +960,7 @@ function sq_fwrite($fp, $string) { * * @param string $charset charset used for encoding. default to us-ascii, 'auto' uses $default_charset global value. * @return array html translation array + * @since 1.5.1 */ function sq_get_html_translation_table($table,$quote_style=ENT_COMPAT,$charset='us-ascii') { global $default_charset; @@ -999,6 +1024,7 @@ function sq_get_html_translation_table($table,$quote_style=ENT_COMPAT,$charset=' * * @param string $charset charset used for encoding. defaults to 'us-ascii', 'auto' uses $default_charset global value. * @return string sanitized string + * @since 1.5.1 */ function sq_htmlentities($string,$quote_style=ENT_COMPAT,$charset='us-ascii') { // get translation table @@ -1057,6 +1083,13 @@ function sq_mb_list_encodings() { if (! function_exists('mb_internal_encoding')) return array(); + // php 5+ function + if (function_exists('mb_list_encodings')) { + $ret = mb_list_encodings(); + array_walk($ret,'sq_lowercase_array_vals'); + return $ret; + } + // don't try to test encodings, if they are already stored in session if (sqgetGlobalVar('mb_supported_encodings',$mb_supported_encodings,SQ_SESSION)) return $mb_supported_encodings; @@ -1107,6 +1140,17 @@ function sq_mb_list_encodings() { return $supported_encodings; } +/** + * Callback function used to lowercase array values. + * @param string $val array value + * @param mixed $key array key + * @since 1.5.1 + */ +function sq_lowercase_array_vals(&$val,$key) { + $val = strtolower($val); +} + + /** * Function returns number of characters in string. * @@ -1119,9 +1163,12 @@ function sq_mb_list_encodings() { * @since 1.5.1 * @return integer number of characters in string */ -function sq_strlen($str, $charset=''){ +function sq_strlen($str, $charset=null){ // default option - if ($charset=='') return strlen($str); + if (is_null($charset)) return strlen($str); + + // lowercase charset name + $charset=strtolower($charset); // use automatic charset detection, if function call asks for it if ($charset=='auto') { @@ -1130,9 +1177,6 @@ function sq_strlen($str, $charset=''){ $charset=$default_charset; } - // lowercase charset name - $charset=strtolower($charset); - // Use mbstring only with listed charsets $aList_of_mb_charsets=array('utf-8','big5','gb2312','gb18030','euc-jp','euc-cn','euc-tw','euc-kr'); -- 2.25.1