| core_util

# Class: Bs_String Source Location: /core/util/Bs_String.class.php
### Class Overview
    Bs_Object
       |
       --Bs_String
This static class provides many useful string methods. #### Author(s): andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org> #### Version: 4.3.$Revision: 1.6 $ $Date: 2003/11/19 08:18:13 $ #### Copyright: blueshoes.org | ### Methods Bs_String addLineNumbers booleanSearchQuery clean endsWith endsWithI escapeForRegexp hasSpecialChars insert inStr inStrI isLower isUpper lcFirst left mid normalize oneOf removeFromToInt right rot13 sow startsWith startsWithI strrpos studlyCapsToSeparated ucWords
### Inherited Variables | ### Inherited Methods #### Class: Bs_Object Bs_Object::Bs_Object() Bs_Object::getErrors() Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack. Bs_Object::getLastError() Basic error handling: Get last error string from the global Bs_Error-error stack. Bs_Object::getLastErrors() Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors(). Bs_Object::persist() Persists this object by serializing it and saving it to a file with unique name. Bs_Object::setError() Basic error handling: Push an error string on the global Bs_Error-error stack. Bs_Object::toHtml() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::toString() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::unpersist() Fetches an object that was persisted with persist()
### Class Details [line 41] This static class provides many useful string methods. Caution: there is a problem with php's strToUpper() and strToLower(). the manual reads: Note that 'alphabetic' is determined by the current locale. This means that in i.e. the default "C" locale, characters such as umlaut-A (Ä) will not be converted. many functions (in this class and everywhere else) use the 2 functions. so expect problems with äöüéAÖÜ and the like. i think we'd need selfmade implementations which convert any chars, not regarding 'default "C" locale'. i wish php would come with params for the functions. Sam: Bs_String must be cleand. Check for my comments 'Sam:' dependencies: none. #### Tags:
pattern: | singleton: (pseudostatic)
todo: | see http://www.phpclasses.org/browse.html/file/1366.html
access: | public
version: | 4.3.$Revision: 1.6 $ $Date: 2003/11/19 08:18:13 $
copyright: | blueshoes.org
author: | andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>
[ Top ] ### Class Methods ### constructor Bs_String [line 47]
`Bs_String Bs_String( )`
constructor. [ Top ] ### method addLineNumbers [line 723]
`void addLineNumbers( string &$str, [int $start = 1], [int $indent = 3])`
Add line number to the left of a given string. E.g. echo addLineNumbers($s="aaaaa\n\nBBB\nddddd\n", $start=2); 2: aaaaa 3: 4: BBB 5: ddddd 6: #### Parameters:
string | &$str |
int | $start | start the numbering with this number. Default is 1
int | $indent | min indent space on the left. Default is 3.
[ Top ] ### method booleanSearchQuery [line 815]
`string booleanSearchQuery( [string $searchString = ""], [string $searchFieldString = ""])`
deprecated, use Bs_TextUtil->parseSearchQuery() !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Takes an altavista like search string "hello +world -foobar" and gives a part of a where clause for sql. please use the IndexServer for these things. it offers alot more and does it cleaner. ask andrej or tell him if you're going to use this function. thanx. NOTE: BETTER USE THE IndexServer!! no support for () yet, like "+hello AND (foo OR bar)" no support for "" yet, like "+"hello world" +"foo bar" for example we support this query: +this and this und this -notthis not notthis nicht nichtdas but not ths one: "hello world" and (tom or tim) all user input is converted to lower case and trimmed. the following operators are accepted: and, und, + not, nicht, - or #### Tags:
return: | returns a string with a part of a where clause for sql queries
#### Parameters:
string | $searchString | string that the user typed into the webform as keywords, example "hello +world -notthis and this und dieses nicht dashier not dasauchnicht", default = no keywords
string | $searchFieldString | space separated list of db fields to search, example "caption street location", default = no fields
[ Top ] ### method clean [line 443]
`string clean( $str $str, [$type $type = 'alphanum'], [string $allowThese = ''])`
This function strips off certain characters from the passed string based on the type specified. The following types are handled, default is 'alphanum': alpha -> removes !(a-z A-Z) noalpha -> removes a-z A-Z num -> removes !(0-9) nonum -> removes 0-9 alphanum -> removes !(a-z A-Z 0-9) noalphanum -> removes a-z A-Z 0-9 nohtmlentities -> remove things like &auml; to strip off html, still use php's strip_tags(). the $allowThese param was added in bs4.5 and is only supported for the types: alpha, num, alphanum #### Parameters:
string | $allowThese | (string of characters that will be allowed. eg "._" for dot and underscore. read above.)
$str | $str | string
$type | $type | type
[ Top ] ### method endsWith [line 251]
`bool endsWith( string $haystack, string $needle, [bool $ignoreSpaces = TRUE])`
tells whether $haystack ends with $needle. eg "hello world" ends with "world". if $ignoreSpaces is set to true, trim() will be used on $haystack. there is no function rtrim() in php :( #### Tags:
see: | endsWithI() startsWith() startsWithI()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
bool | $ignoreSpaces | default is true
[ Top ] ### method endsWithI [line 273]
`bool endsWithI( string $haystack, string $needle, [bool $ignoreSpaces = TRUE])`
same as endsWith() but not case sensitive. #### Tags:
see: | endsWith() startsWith() startsWithI()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
bool | $ignoreSpaces | default is true
[ Top ] ### method escapeForRegexp [line 698]
`string escapeForRegexp( string $string, [string $borderChar = '/'])`
Adds backslashs to all char in a string that could iterfear with a regular expression. Sometimes you want to use a random string in a regular expression, but you don't know if the used string has special regex-characters like "^.[$()|*+?{\" in it that need to be escaped (with a backslash). Appart from the know regex-characters we also have to escape the 'border'-char; often it's a '/' (foreslash) but can be any other char (rtfm of regex for details). E.g. Following do the same and are valid regexs: preg_match('/^#/', $foo) // border-char used is a '/' (foreslash) preg_match('`^#`', $foo) // border-char used is a '`' (backtick) note: there is preg_quote(), was not aware of that. should we deprecate this one? guess so. sam? #### Tags:
access: | public
#### Parameters:
string | $string |
string | $borderChar | (see above)
[ Top ] ### method hasSpecialChars [line 380]
`bool hasSpecialChars( string $myString, [int $charSet = 7], [array $myExceptions = NULL])`
tells whether there are "special" characters in a string or not. based on param $charSet, the following characters are considered 'normal': charSet 1 a-z charSet 2 A-Z charSet 3 a-z A-Z charSet 4 0-9 charSet 5 a-z 0-9 charSet 6 A-Z 0-9 charSet 7 a-z A-Z 0-9 ascii codes: 0-9 -> 048 - 057 A-Z -> 065 - 090 a-z -> 097 - 122 other characters that need to be treated 'normal' can be given in the param array $myExceptions. #### Tags:
todo: | i bet this method could be optimized alot using regexp.
#### Parameters:
string | $myString | the string to be checked
int | $charSet | default is 7 (see abmove)
array | $myExceptions | array with chars that should be considered as "normal" chars instead of "specials".
[ Top ] ### method insert [line 116]
`bool insert( string &$hayStack, string $addThis, int $position)`
Insert $addThis into $haystack at $position. the first position of $haystack is 0 not 1. example: ($new will be 'hello') $old = 'hllo'; $new = $Bs_String->insert($old, 'e', 1) OR $new='default'; #### Tags:
return: | TRUE on success, FALSE on failure ($position is not >= 0 or the position is out of range).
#### Parameters:
string | &$hayStack |
string | $addThis |
int | $position |
[ Top ] ### method inStr [line 181]
`bool inStr( string $haystack, string $needle)`
Tells if needle is part of haystack example: $haystack = "hello world"; $needle = "lo"; $x = $BsString->instr($haystack, $needle); true will be returned. #### Tags:
see: | Bs_String::inStrI()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
[ Top ] ### method inStrI [line 196]
`bool inStrI( string $haystack, string $needle)`
same as inStr() but not case sensitive. #### Tags:
see: | Bs_String::inStr()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
[ Top ] ### method isLower [line 520]
`bool isLower( string $string)`
Tells if the given string is all lowercase. #### Parameters:
string | $string |
[ Top ] ### method isUpper [line 510]
`bool isUpper( string $string)`
Tells if the given string is all uppercase. #### Parameters:
string | $string |
[ Top ] ### method lcFirst [line 579]
`string lcFirst( string $string)`
converts the first character of the given string to lower case. php only has an ucFirst as of 2002/12/16. #### Parameters:
string | $string |
[ Top ] ### method left [line 60]
`string left( string $haystack, [number $num = 0])`
returns $num chars from the left side of $haystack #### Tags:
see: | Bs_String::right(), Bs_String::mid()
#### Parameters:
string | $haystack | the string to be looked at
number | $num | the number of chars to be returned. '' means all. 0 means none.
[ Top ] ### method mid [line 93]
`string mid( string $haystack, [number $start = 1], [number $num = 0])`
returns $num chars from the middle of $haystack, beginning with $start (included). note: $haystack begins with char 1, not with char 0. example: string "hello" number 12345 #### Tags:
see: | Bs_String::left(), Bs_String::right()
#### Parameters:
string | $haystack | the string to be looked at.
number | $start | the number of the character where to start. a string always begins at char 1 not 0!
number | $num | the number of chars to be returned. '' means all to the end. 0 means none.
[ Top ] ### method normalize [line 483]
`string normalize( string $param, [bool $specialDouble = TRUE])`
Converts each special character (áéíÁÈÒÖ...) to their normal character (aeiAEOO...) This function is made to use special characters (192-223 and 224-255 in ascii table). (hope so) #### Tags:
return: | the converted string.
#### Parameters:
string | $param | the string you want to be converted
bool | $specialDouble | (translate some chars specially, like ä=>ae not ä=>a. default is TRUE.)
[ Top ] ### method oneOf [line 339]
`string oneOf( string 0)`
Return one of the given arguements randomly. this function can take 0-n string params, so the following syntax is ok: $x = $Bs_String->oneOf(); $x = $Bs_String->oneOf("hello"); $x = $Bs_String->oneOf("hello", "world", "foobar", "something else", "", "bla bla bla"); it will randomly pick one of the params and return it. this method has the disadvantage to take all arguements by value. some optimization can be done bye using useOneOfArray($array) instead and passing the array by ref. if no arguement was given, an empty string is returned. #### Tags:
see: | useOneOfArray()
#### Parameters:
string | 0 | 0-n string params can be given.
[ Top ] ### method removeFromToInt [line 159]
`string removeFromToInt( string $string, int $from, int $to)`
removes a part of a $string. starts at $from, ends at $to. caution: as usual pos numbers start at 0 not 1, see examples. examples: (see ecg) removeFromToInt('hello world', 2, 6); will return 'heorld' removeFromToInt('hello world', 0, 30); will return '' removeFromToInt('', 0, 30); will return '' #### Tags:
see: | $this->removeFromNumInt()
#### Parameters:
string | $string |
int | $from |
int | $to |
[ Top ] ### method right [line 74]
`string right( string $haystack, [number $num = 0])`
returns $num chars from the right side of $haystack #### Tags:
see: | Bs_String::left(), Bs_String::mid()
#### Parameters:
string | $haystack | the string to be looked at
number | $num | the number of chars to be returned. '' means all. 0 means none.
[ Top ] ### method rot13 [line 768]
`void rot13( mixed $rot13text)`
ROT13 function - a function to encode and decode text strings [ Top ] ### method sow [line 740]
`void sow( mixed $string, mixed $insert, mixed $increment)`
Inserts a string into another string every increment. example: sow("hello world", "@", 3) => "hel@lo @wor@ld" #### Tags:
copyright: | nathan@cjhunter.com 29/08/2000 http://www.zend.com/codex.php?id=253&single=1
[ Top ] ### method startsWith [line 211]
`bool startsWith( string $haystack, string $needle, [bool $ignoreSpaces = TRUE])`
tells whether $haystack starts with $needle. eg "hello world" starts with "hello". if $ignoreSpaces is set to true, ltrim() will be used on $haystack. #### Tags:
see: | startsWithI() endsWith() endsWithI()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
bool | $ignoreSpaces | default is true
[ Top ] ### method startsWithI [line 235]
`bool startsWithI( string $haystack, string $needle, [bool $ignoreSpaces = TRUE])`
same as startsWith() but not case sensitive. #### Tags:
todo: | optimize this shit. imagine a really huge $haystack and a small $needle. all $haystack is converted to lowercase. only the strlen($needle) chars would need to be converted. and passed over. same for endsWithI. better use regexp here.
see: | startsWith() endsWith() endsWithI()
#### Parameters:
string | $haystack | the string to be looked at
string | $needle | the string to be looked for
bool | $ignoreSpaces | default is true
[ Top ] ### method strrpos [line 301]
`int strrpos( string $haystack, string $needle, [int $offset = NULL])`
same as php's strrpos() but allows a string (instead of a char) as 2nd param and $offset as 3rd param, just as php's strpos() does. if needle is not found, returns FALSE (just as the php function does). because 0 is a valid return value, check for === FALSE. this is the same problem as with the other such php functions. don't expect optimized code here. what we do is strpos() until the end, and the return the pos of the last found one. hack, but helps. examples: (see ecg) strrpos('abc bold abc', 'abc'); //will return 16 strrpos('abc bold abc', 'abc', 5); //will return 0 #### Tags:
return: | the numeric position, first position = 0.
throws: | bool FALSE.
#### Parameters:
string | $haystack |
string | $needle |
int | $offset |
[ Top ] ### method studlyCapsToSeparated [line 609]
`string studlyCapsToSeparated( string $word)`
takes a word written in studly caps and returns it in separated words. rules: all initial letters of the words will be uppercase ucWords(). a row of UPPERCASE letters won't be splitted, eg 'DB', see examples. examples: studlyCapsToSeparated('dbAbstractionLayer'); //will return 'Db Abstraction Layer' studlyCapsToSeparated('DbAbstractionLayer'); //will return 'Db Abstraction Layer' studlyCapsToSeparated('DBAbstractionLayer'); //will return 'DB Abstraction Layer' studlyCapsToSeparated('fooBar345'); //will return 'Foo Bar 345' studlyCapsToSeparated('foo345Bar'); //will return 'Foo 345 Bar' studlyCapsToSeparated('foo345bar'); //will return 'Foo 345 Bar' studlyCapsToSeparated('someDB'); //will return 'Some DB' studlyCapsToSeparated('someDBLayer'); //will return 'Some DB Layer' #### Tags:
access: | public
#### Parameters:
string | $word |
[ Top ] ### method ucWords [line 549]
`string ucWords( string $string, [array $addChars = null])`
Uppercase the first character of each word in a string. Returns a string with the first character of each word in str capitalized, if that character is alphabetic. this method extends php's ucWords() function. php's implementation only converts characters after a 'whitespace characters': space, form-feed, newline, carriage return, horizontal tab, vertical tab here you can define the characters yourself. recommended characters: the ones from php (see above) the minus "-" (i have coded the method because of this one) note: we face the strToUpper/Lower problem here that is described in the header of this class (foreign characters like ä => Ä). #### Parameters:
string | $string |
array | $addChars | (chars that should be treated like the default 'whitespace' chars.)
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:12:58 +0100 by phpDocumentor 1.2.3