Docs for page strings.php

/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