File/nasmail/functions/strings.php

Description

strings.php

This code provides various string manipulation functions that are used by the rest of the SquirrelMail code.

This script contains modifications ported from SquirrelMail 1.4.9+. See commits tagged with SM-PATCH keyword. Modifications are copyrighted by the SquirrelMail Project Team. Copyright (c) 2007 The SquirrelMail Project Team

  • version: $Id: strings.php 1497 2009-11-22 14:32:18Z tokul $
  • copyright: (c) 1999-2006 The SquirrelMail Project Team
  • copyright: (c) 2006-2009 The NaSMail Project
  • license: GNU Public License
Includes
 include_once (SM_PATH.'plugins/compatibility/functions.php') (line 51)

NaSMail compatibility plugin include

 include_once (SM_PATH.'functions/global.php') (line 46)

There can be a circular issue with includes, where the $version string is 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.

Functions
GenerateRandomString (line 535)

Generates a random string from the caracter set you pass in

  • return: the random string
string GenerateRandomString (int $size, string $chars, [int $flags = 0])
  • int $size: size the size of the string to generate
  • string $chars: chars a string containing the characters to use
  • int $flags: 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
get_location (line 274)

get_location

Determines the location to forward to, relative to your server. This is used in HTTP Location: redirects. If set, it uses $config_location_base as the first part of the URL, specifically, the protocol, hostname and port parts. The path is always autodetected.

  • return: the base url for this SquirrelMail installation
string get_location ()
nsm_addslashes (line 963)

PHP addslashes replacement that does not depend on correct magic_quotes_sybase setting.

  • return: escaped text
  • since: 1.3
string nsm_addslashes (string $str)
  • string $str: text that has to be escaped
nsm_cstrcasecmp (line 948)

Locale insensitive strcasecmp

Function compares two strings in LC_CTYPE=C locale. Arguments and return values are the same as in standard PHP strcasecmp().

  • return: 0 when strings match. negative int, if first string is less that second one. positive int, if first string is greater than second one.
  • link: http://www.php.net/strcasecmp
  • since: 1.3
int nsm_cstrcasecmp (string $str1, string $str2)
  • string $str1
  • string $str2
nsm_cstrtolower (line 911)

Locale insensitive strtolower

Function converts string to lower case in LC_CTYPE=C locale

  • return: lowercased text
string nsm_cstrtolower (string $string)
  • string $string: string text
nsm_cstrtoupper (line 927)

Locale insensitive strtoupper

Function converts string to upper case in LC_CTYPE=C locale

  • return: text in upper case
string nsm_cstrtoupper (string $string)
  • string $string: string text
nsm_process_upload_errors (line 1006)

Converts PHP 4.2+ upload error codes to human readable (and translated) string

Function always runs in NaSMail gettext domain. Don't use it to detect upload errors. Function only provides error message _after_ upload error is detected.

  • return: Translated upload error message or empty string
  • since: 1.4
string nsm_process_upload_errors (string $fieldname)
  • string $fieldname: name of attachment field
nsm_setint_u32 (line 1060)

Makes sure that number is 32bit unsigned integer

Primary function use - sanitizing of passed_id value.

  • return: Unsigned 32bit integer. Some values are not actually evaluated as integers by PHP. If argument is not unsigned 32bit integer, function returns 0.
  • since: 1.4
float nsm_setint_u32 (mixed $number)
  • mixed $number: Value that must be represented as unsigned 32bit integer
nsm_string_compare (line 1084)

Compares two strings

Function fixes PHP quirk, when "0" is treated as integer and string evaluation checks return unpredicted results.

  • since: 1.7
boolean nsm_string_compare (string $str1, string $str2)
  • string $str1
  • string $str2
nsm_str_pad (line 980)

Multibyte aware string padding

Currently code allows only ascii symbols in $pad_string. If pad is not in ascii, code won't be able to calculate correct pad string.

  • return: Padded string
  • since: 1.4
string nsm_str_pad (string $input, int $pad_length, [string $pad_string = ' '], [int $pad_type = STR_PAD_RIGHT], [string $charset = 'utf-8'])
  • string $input: text
  • int $pad_length
  • string $pad_string: String used for padding
  • int $pad_type: Padding type. PHP STR_PAD_RIGHT,STR_PAD_LEFT,STR_PAD_BOTH constants.
  • string $charset: Input character set
OneTimePadCreate (line 486)

Creates encryption key

Creates an encryption key for encrypting the password stored in the cookie. The encryption key itself is stored in the session.

  • return: the encryption key
string OneTimePadCreate ([int $length = 100])
  • int $length: length optional, length of the string to generate
OneTimePadDecrypt (line 381)

Decrypts a password from the cookie

Decrypts a password from the cookie, encrypted by OneTimePadEncrypt. This uses the encryption key that is stored in the session.

  • return: the decrypted password
string OneTimePadDecrypt (string $string, string $epad)
  • string $string: string the string to decrypt
  • string $epad: epad the encryption key from the session
OneTimePadEncrypt (line 351)

Encrypts password

These functions are used to encrypt the password before it is stored in a cookie. The encryption key is generated by OneTimePadCreate();

  • return: the base64-encoded encrypted password
string OneTimePadEncrypt (string $string, string $epad)
  • string $string: string the (password)string to encrypt
  • string $epad: epad the encryption key
php_self (line 220)

php_self

Creates an URL for the page calling this function, using either the PHP global REQUEST_URI, or the PHP global PHP_SELF with QUERY_STRING added.

  • return: the complete url for this page
string php_self ()
quoteimap (line 568)

Escapes special characters for use in IMAP commands.

  • return: the escaped string
  • deprecated: 1.7. Use nsm_imap_quote_string.
string quoteimap (string $str)
  • string $str: the string to escape
readShortMailboxName (line 199)

If $haystack is a full mailbox name and $needle is the mailbox separator character, returns the last part of the mailbox name.

  • return: the last part of the mailbox name
string readShortMailboxName (string $haystack, string $needle)
  • string $haystack: haystack full mailbox name to search
  • string $needle: needle the mailbox separator character
RemoveSlashes (line 601)

Removes slashes from every element in the array

Slashes are removed from array keys and values

void RemoveSlashes (array &$array)
  • array &$array: array Parsed array
show_readable_size (line 503)

Returns a string showing the size of the message/attachment.

  • return: the filesize in human readable format
string show_readable_size (int $bytes)
  • int $bytes: bytes the filesize in bytes
sm_print_r (line 630)

Print variable

sm_print_r($some_variable, [$some_other_variable [, ...]]);

Debugging function - does the same as print_r, but makes sure special characters are converted to htmlentities first. This will allow values like <some@email.address> to be displayed. If variable is object, object methods are printed. The output is wrapped in <pre> and </pre> tags.

void sm_print_r ()
sqm_baseuri (line 249)

Find out where scripts live and try to be smart about it.

The only problem would be when scripts live in directories called "src", "functions", or "plugins", but people who do that need to be beaten with a steel pipe anyway.

  • return: the base uri of squirrelmail installation.
string sqm_baseuri ()
sqUnWordWrap (line 115)

Does the opposite of sqWordWrap()

void sqUnWordWrap (string &$body)
  • string &$body: body the text to un-wordwrap
sqWordWrap (line 67)

Wraps text at $wrap characters

Has a problem with special HTML characters, so call this before you do character translation.

Specifically, &#039 comes up as 5 characters instead of 1. This should not add newlines to the end of lines.

void sqWordWrap (string &$line, int $wrap, [string $charset = null])
  • string &$line: line Rewrapped text
  • int $wrap: wrap max characters per line
  • string $charset: charset character set
sq_fwrite (line 663)

version of fwrite which checks for failure

  • return: false or number of written bytes
int|bool sq_fwrite (resource $fp, string $string)
  • resource $fp: fp File handle
  • string $string: string Written string
sq_is8bit (line 681)

Tests if string contains 8bit symbols.

If charset is not set, function defaults to utf-8.

  • return: true if 8bit symbols are detected
bool sq_is8bit (string $string, [string $charset = ''])
  • string $string: string tested string
  • string $charset: charset charset used in a string
sq_lowercase_array_vals (line 823)

Callback function used to lowercase array values.

void sq_lowercase_array_vals (string &$val, mixed $key)
  • string &$val: val array value
  • mixed $key: key array key
sq_mb_list_encodings (line 753)

Replacement of mb_list_encodings function

This function provides replacement for function that is available only in php 5.x. Function does not test all mbstring encodings.

Supported strings are stored in session in order to reduce number of mb_internal_encoding function calls.

If mb_list_encodings() function is present, code uses it. Main difference from original function behaviour - array values are lowercased in order to simplify use of returned array in in_array() checks.

If you want to test all mbstring encodings - fill $list_of_encodings array.

  • return: list of encodings supported by php mbstring extension
array sq_mb_list_encodings ()
sq_mt_randomize (line 443)

Init random number generator

This function initializes the random number generator fairly well. It also only initializes it once, so you don't accidentally get the same 'random' numbers twice in one session.

void sq_mt_randomize ()
sq_mt_seed (line 413)

Randomizes the mt_rand() function.

Toss this in strings or integers and it will seed the generator appropriately. With strings, it is better to get them long. Use md5() to lengthen smaller strings.

void sq_mt_seed (int|string $Val)
  • int|string $Val: val a value to seed the random number generator
sq_strlen (line 710)

Function returns number of characters in string.

Returned number might be different from number of bytes in string, if $charset is multibyte charset. Detection depends on mbstring functions. If mbstring does not support tested multibyte charset, vanilla string length function is used.

  • return: number of characters in string
integer sq_strlen (string $str, [string $charset = null])
  • string $str: str string
  • string $charset: charset charset
sq_strpos (line 882)

Wrapper that is used to switch between vanilla and multibyte strpos functions.

string sq_strpos (string $haystack, mixed $needle, integer $offset, [string $charset = 'utf-8'])
  • string $haystack: haystack text
  • mixed $needle: needle
  • integer $offset: offset
  • string $charset: charset character set
sq_substr (line 847)

Wrapper that is used to switch between vanilla and multibyte substr functions.

string sq_substr (string $string, integer $start, integer $length, [string $charset = 'utf-8'])
  • string $string: string text
  • integer $start: start start position
  • integer $length: length number of characters
  • string $charset: charset Character set
sq_trim_value (line 831)

Callback function to trim whitespace from a value, to be used in array_walk

void sq_trim_value (string &$value)
  • string &$value: value value to trim
TrimArray (line 579)

Trims array

Trims every element in the array, ie. remove the first char of each element Obsolete: will probably removed soon

void TrimArray (array &$array)
  • array &$array: array the array to trim
truncateWithEntities (line 152)

Truncates a string and take care of html encoded characters

  • return: Trimmed string
string truncateWithEntities (string $s, int $iTrimAt)
  • string $s: s string to truncate
  • int $iTrimAt: iTrimAt Trim at nn characters

Documentation generated on Sun, 22 Nov 2009 17:36:51 +0200 by phpDocumentor 1.4.3