HordeString
in package
Provides static methods for charset and locale safe string manipulation.
Copyright 2003-2017 Horde LLC (http://www.horde.org/)
See the enclosed file LICENSE for license information (LGPL). If you did not receive this file, see http://www.horde.org/licenses/lgpl21.
Tags
Table of Contents
- $_lowers : array<string|int, mixed>
- lower() cache.
- $_uppers : array<string|int, mixed>
- upper() cache.
- abbreviate() : string
- Return an abbreviated string, with characters in the middle of the excessively long string replaced by '...'.
- common() : string
- Returns the common leading part of two strings.
- convertCharset() : mixed
- Converts a string from one charset to another.
- convertToUtf8() : string
- Try to convert a string to UTF-8.
- ipos() : int
- Returns the numeric position of the first case-insensitive occurrence of $needle in the $haystack string.
- isAlpha() : bool
- Returns true if the every character in the parameter is an alphabetic character.
- isLower() : bool
- Returns true if ever character in the parameter is a lowercase letter in the current locale.
- isUpper() : bool
- Returns true if every character in the parameter is an uppercase letter in the current locale.
- length() : int
- Returns the character (not byte) length of a string.
- lower() : string
- Makes a string lowercase.
- pad() : string
- Returns a string padded to a certain length with another string.
- pos() : int
- Returns the numeric position of the first occurrence of $needle in the $haystack string.
- regexMatch() : array<string|int, mixed>
- Performs a multibyte safe regex match search on the text provided.
- ripos() : int
- Returns the numeric position of the last case-insensitive occurrence of $needle in the $haystack string.
- rpos() : int
- Returns the numeric position of the last occurrence of $needle in the $haystack string.
- substr() : string
- Returns part of a string.
- trimUtf8Bom() : string
- Strip UTF-8 byte order mark (BOM) from string data.
- truncate() : string
- Return a truncated string, suitable for notifications.
- ucfirst() : string
- Returns a string with the first letter capitalized if it is alphabetic.
- ucwords() : string
- Returns a string with the first letter of each word capitalized if it is alphabetic.
- upper() : string
- Makes a string uppercase.
- validUtf8() : bool
- Check to see if a string is valid UTF-8.
- wordwrap() : string
- Wraps the text of a message.
- wrap() : string
- Wraps the text of a message.
- _convertCharset() : string
- Internal function used to do charset conversion.
- _mbstringCharset() : string
- Workaround charsets that don't work with mbstring functions.
- _pos() : int
- Perform string position searches.
Properties
$_lowers
lower() cache.
protected
static array<string|int, mixed>
$_lowers
= []
$_uppers
upper() cache.
protected
static array<string|int, mixed>
$_uppers
= []
Methods
abbreviate()
Return an abbreviated string, with characters in the middle of the excessively long string replaced by '...'.
public
static abbreviate(string $text[, int $length = 20 ]) : string
Parameters
- $text : string
-
The original string.
- $length : int = 20
-
The length at which to abbreviate.
Return values
string —The abbreviated string, if longer than $length.
common()
Returns the common leading part of two strings.
public
static common(string $str1, string $str2) : string
Parameters
- $str1 : string
-
A string.
- $str2 : string
-
Another string.
Return values
string —The start of $str1 and $str2 that is identical in both.
convertCharset()
Converts a string from one charset to another.
public
static convertCharset(mixed $input, string $from, string $to[, bool $force = false ]) : mixed
Uses the iconv or the mbstring extensions. The original string is returned if conversion failed or none of the extensions were available.
Parameters
- $input : mixed
-
The data to be converted. If $input is an an array, the array's values get converted recursively.
- $from : string
-
The string's current charset.
- $to : string
-
The charset to convert the string to.
- $force : bool = false
-
Force conversion?
Return values
mixed —The converted input data.
convertToUtf8()
Try to convert a string to UTF-8.
public
static convertToUtf8(string $string) : string
This method is kind of a hotfix for IMP and should probably be refactored.
Throws if source charset could not be detected or conversion failed
Parameters
- $string : string
-
The string to convert
Tags
Return values
string —The string in UTF-8
ipos()
Returns the numeric position of the first case-insensitive occurrence of $needle in the $haystack string.
public
static ipos(string $haystack, string $needle, int $offset[, string $charset = 'UTF-8' ]) : int
Parameters
- $haystack : string
-
The string to search through.
- $needle : string
-
The string to search for.
- $offset : int
-
Character in $haystack to start searching at.
- $charset : string = 'UTF-8'
-
Charset of $needle.
Tags
Return values
int —The position of first case-insensitive occurrence.
isAlpha()
Returns true if the every character in the parameter is an alphabetic character.
public
static isAlpha(string $string, string $charset) : bool
Parameters
- $string : string
-
The string to test.
- $charset : string
-
The charset to use when testing the string.
Return values
bool —True if the parameter was alphabetic only.
isLower()
Returns true if ever character in the parameter is a lowercase letter in the current locale.
public
static isLower(string $string, string $charset) : bool
Parameters
- $string : string
-
The string to test.
- $charset : string
-
The charset to use when testing the string.
Return values
bool —True if the parameter was lowercase.
isUpper()
Returns true if every character in the parameter is an uppercase letter in the current locale.
public
static isUpper(string $string, string $charset) : bool
Parameters
- $string : string
-
The string to test.
- $charset : string
-
The charset to use when testing the string.
Return values
bool —True if the parameter was uppercase.
length()
Returns the character (not byte) length of a string.
public
static length(string $string[, string $charset = 'UTF-8' ]) : int
Parameters
- $string : string
-
The string to return the length of.
- $charset : string = 'UTF-8'
-
The charset to use when calculating the string's length.
Return values
int —The string's length.
lower()
Makes a string lowercase.
public
static lower(string $string[, bool $locale = false ][, string $charset = null ]) : string
Parameters
- $string : string
-
The string to be converted.
- $locale : bool = false
-
If true the string will be converted based on a given charset, locale independent else.
- $charset : string = null
-
If $locale is true, the charset to use when converting.
Return values
string —The string with lowercase characters.
pad()
Returns a string padded to a certain length with another string.
public
static pad(string $input, int $length[, string $pad = ' ' ][, int $type = STR_PAD_RIGHT ][, string $charset = 'UTF-8' ]) : string
This method behaves exactly like str_pad() but is multibyte safe.
Parameters
- $input : string
-
The string to be padded.
- $length : int
-
The length of the resulting string.
- $pad : string = ' '
-
The string to pad the input string with. Must be in the same charset like the input string.
- $type : int = STR_PAD_RIGHT
-
The padding type. One of STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH.
- $charset : string = 'UTF-8'
-
The charset of the input and the padding strings.
Return values
string —The padded string.
pos()
Returns the numeric position of the first occurrence of $needle in the $haystack string.
public
static pos(string $haystack, string $needle, int $offset[, string $charset = 'UTF-8' ]) : int
Parameters
- $haystack : string
-
The string to search through.
- $needle : string
-
The string to search for.
- $offset : int
-
Character in $haystack to start searching at.
- $charset : string = 'UTF-8'
-
Charset of $needle.
Return values
int —The position of first occurrence.
regexMatch()
Performs a multibyte safe regex match search on the text provided.
public
static regexMatch(string $text, array<string|int, mixed> $regex[, string $charset = null ]) : array<string|int, mixed>
Parameters
- $text : string
-
The text to search.
- $regex : array<string|int, mixed>
-
The regular expressions to use, without perl regex delimiters (e.g. '/' or '|').
- $charset : string = null
-
The character set of the text.
Return values
array<string|int, mixed> —The matches array from the first regex that matches.
ripos()
Returns the numeric position of the last case-insensitive occurrence of $needle in the $haystack string.
public
static ripos(string $haystack, string $needle, int $offset[, string $charset = 'UTF-8' ]) : int
Parameters
- $haystack : string
-
The string to search through.
- $needle : string
-
The string to search for.
- $offset : int
-
Character in $haystack to start searching at.
- $charset : string = 'UTF-8'
-
Charset of $needle.
Tags
Return values
int —The position of last case-insensitive occurrence.
rpos()
Returns the numeric position of the last occurrence of $needle in the $haystack string.
public
static rpos(string $haystack, string $needle, int $offset[, string $charset = 'UTF-8' ]) : int
Parameters
- $haystack : string
-
The string to search through.
- $needle : string
-
The string to search for.
- $offset : int
-
Character in $haystack to start searching at.
- $charset : string = 'UTF-8'
-
Charset of $needle.
Return values
int —The position of last occurrence.
substr()
Returns part of a string.
public
static substr(string $string, int $start[, int $length = null ][, string $charset = 'UTF-8' ]) : string
Parameters
- $string : string
-
The string to be converted.
- $start : int
-
The part's start position, zero based.
- $length : int = null
-
The part's length.
- $charset : string = 'UTF-8'
-
The charset to use when calculating the part's position and length, defaults to current charset.
Return values
string —The string's part.
trimUtf8Bom()
Strip UTF-8 byte order mark (BOM) from string data.
public
static trimUtf8Bom(string $str) : string
Parameters
- $str : string
-
Input string (UTF-8).
Return values
string —Stripped string (UTF-8).
truncate()
Return a truncated string, suitable for notifications.
public
static truncate(string $text[, int $length = 100 ]) : string
Parameters
- $text : string
-
The original string.
- $length : int = 100
-
The maximum length.
Return values
string —The truncated string, if longer than $length.
ucfirst()
Returns a string with the first letter capitalized if it is alphabetic.
public
static ucfirst(string $string[, bool $locale = false ][, string $charset = null ]) : string
Parameters
- $string : string
-
The string to be capitalized.
- $locale : bool = false
-
If true the string will be converted based on a given charset, locale independent else.
- $charset : string = null
-
The charset to use, defaults to current charset.
Return values
string —The capitalized string.
ucwords()
Returns a string with the first letter of each word capitalized if it is alphabetic.
public
static ucwords(string $string[, bool $locale = false ][, string $charset = null ]) : string
Sentences are splitted into words at whitestrings.
Parameters
- $string : string
-
The string to be capitalized.
- $locale : bool = false
-
If true the string will be converted based on a given charset, locale independent else.
- $charset : string = null
-
The charset to use, defaults to current charset.
Return values
string —The capitalized string.
upper()
Makes a string uppercase.
public
static upper(string $string[, bool $locale = false ][, string $charset = null ]) : string
Parameters
- $string : string
-
The string to be converted.
- $locale : bool = false
-
If true the string will be converted based on a given charset, locale independent else.
- $charset : string = null
-
If $locale is true, the charset to use when converting. If not provided the current charset.
Return values
string —The string with uppercase characters.
validUtf8()
Check to see if a string is valid UTF-8.
public
static validUtf8(string $text) : bool
Parameters
- $text : string
-
The text to check.
Return values
bool —True if valid UTF-8.
wordwrap()
Wraps the text of a message.
public
static wordwrap(string $string[, int $width = 75 ][, string $break = "
" ][, bool $cut = false ][, bool $line_folding = false ]) : string
Parameters
- $string : string
-
String containing the text to wrap.
- $width : int = 75
-
Wrap the string at this number of characters.
- $break : string = " "
-
Character(s) to use when breaking lines.
- $cut : bool = false
-
Whether to cut inside words if a line can't be wrapped.
- $line_folding : bool = false
-
Whether to apply line folding rules per RFC 822 or similar. The correct break characters including leading whitespace have to be specified too.
Return values
string —String containing the wrapped text.
wrap()
Wraps the text of a message.
public
static wrap(string $text[, int $length = 80 ][, string $break_char = "
" ][, bool $quote = false ]) : string
Parameters
- $text : string
-
String containing the text to wrap.
- $length : int = 80
-
Wrap $text at this number of characters.
- $break_char : string = " "
-
Character(s) to use when breaking lines.
- $quote : bool = false
-
Ignore lines that are wrapped with the '>' character (RFC 2646)? If true, we don't remove any padding whitespace at the end of the string.
Return values
string —String containing the wrapped text.
_convertCharset()
Internal function used to do charset conversion.
protected
static _convertCharset(string $input, string $from, string $to) : string
Parameters
- $input : string
-
See self::convertCharset().
- $from : string
-
See self::convertCharset().
- $to : string
-
See self::convertCharset().
Return values
string —The converted string.
_mbstringCharset()
Workaround charsets that don't work with mbstring functions.
protected
static _mbstringCharset(string $charset) : string
Parameters
- $charset : string
-
The original charset.
Return values
string —The charset to use with mbstring functions.
_pos()
Perform string position searches.
protected
static _pos(string $haystack, string $needle, int $offset, string $charset, string $func) : int
Parameters
- $haystack : string
-
The string to search through.
- $needle : string
-
The string to search for.
- $offset : int
-
Character in $haystack to start searching at.
- $charset : string
-
Charset of $needle.
- $func : string
-
Function to use.
Return values
int —The position of occurrence.