blueshoes php application framework and cms            core_util
[ class tree: core_util ] [ index: core_util ] [ all elements ]

Class: Bs_Array

Source Location: /core/util/Bs_Array.class.php

Class Overview

Bs_Object
   |
   --Bs_Array

This static class provides many useful array methods that don't come with php.


Author(s):

Version:

  • 4.3.$Revision: 1.4 $ $Date: 2003/10/29 17:48:43 $

Copyright:

  • blueshoes.org

Methods


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 23]
This static class provides many useful array methods that don't come with php.

knowledge base: o) some of php's array functions (eg array_pop()) renumber the index of vectors. o) the syntax "$array['someObject']->someFunction()" works now.

no dependencies here.




Tags:

pattern:  singleton: (pseudostatic) static
access:  public
version:  4.3.$Revision: 1.4 $ $Date: 2003/10/29 17:48:43 $
copyright:  blueshoes.org
author:  Andrej Arn <at blueshoes dot org>


[ Top ]


Class Methods


constructor Bs_Array [line 29]

Bs_Array Bs_Array( )

constructor.



[ Top ]

method arrayMergeRecursive [line 156]

void arrayMergeRecursive( array $a1, array $a2)

like php's array_merge_recursive() but does not fuck up numeric keys (hashs).

this is real crap in php, imo. (maybe php 4.3 has fixed this.) if a param is not an array it will be ignored.

WARNING: don't use this if your array has recursive references!!!




Tags:

since:  bs4.3
throws:  bool FALSE if none of the given params is an array.
access:  public


Parameters:

array   $a1  
array   $a2  

[ Top ]

method arrayToCode [line 205]

string arrayToCode( array &$array, [string $name = '$array'])

--sam 2002-12-18 Since PHP4.2.0 this could be obsolet in some way. See PHP's function var_export() var_export() : Similar to var_dump() with the exception that the returned representation is valid PHP code.

takes an array and returns a php code string from it. note: there is supposed to be a php function that does the same, have a look and update this info.

example: $array = array('tom', array('fruit'=>"tom's apple is \"green\""), $object, array(15=>20), array()); $string = arrayToCode($array, '$foo'); now $string looks like $foo['0'] = "tom"; $foo['1']['fruit'] = "tom\'s apple is \"green\""; $foo['2'] = ''; $foo['3']['15'] = 20; $foo['4'] = array();

caution I: objects are shown as empty strings. this is not serialize(). caution II: the param $name needs to come with the $ sign. if you use "\$name" instead of '$name" you have to escape the $ sign. note: string values are escaped.




Tags:

see:  php's var_dump and our dump()
throws:  empty string if param $array is not an array or empty.


Parameters:

array   &$array   (hash or vector, any construct)
string   $name   default is 'array' the name to use as the var name in the returned php code.

[ Top ]

method arrayToText [line 272]

string arrayToText( array $data, [int $maxWidth = 75], [string $stringSeparator = ': '], [string $struct2 = FALSE])

takes an array (hash) and formats it as plain text. very usable to include array data in emails, for example.

example: $a = array( 'aaaaaaa aaaaaaaa' => 'asdf asdf asdf asdfjklasdjfasdöljfaösdl fjaösdkljf aösdkf jaösdkf jaösdfk jkaösdfjasdfökjasdffjasd kfjkaösd jfaösd fjaösd fjaösdf', 'bbbbbbbbb' => 'asdf asdf asdf', 'ccc cccccccc cc' => 'asdfjk aöksdl fjkaösdlj föaklsdj faösdkl fjöasdf', ); echo $Bs_Array->arrayToText($a); will spit out: aaaaaaa aaaaaaaa: asdf asdf asdf asdfjklasdjfasdöljfaösdl fjaösdkljf aösdkf jaösdkf jaösdfk jkaösdfjasdfökjasdffjasd kfjkaösd jfaösd fjaösd fjaösdf bbbbbbbbb : asdf asdf asdf ccc cccccccc cc : asdfjk aöksdl fjkaösdlj föaklsdj faösdkl fjöasdf

param $struct2: normally you give a hash where key is the "field name" and value the "value". sometimes that is not possible because you have dublicate "field names". then the latter would overwrite the previous one. for this you can give a hash or vector (the key is ignored so it does not matter) with the structure like: array( array('foo' => 'bar'), array('foo' => 'hello'), array('php' => 'world'), ); set $struct2 to TRUE to tell the method you've used this data structure.




Tags:

todo:  deal with boxed arrays
since:  bs4.3
access:  public


Parameters:

array   $data   (usually a hash)
int   $maxWidth   (default is 75)
string   $stringSeparator   (default is ': ')
string   $struct2   (see above, default is FALSE.)

[ Top ]

method array_merge_recursive [line 138]

void array_merge_recursive( mixed $a1, mixed $a2)

alias for arrayMergeRecursive() so look there.

stupid me. i have added this in 4.3 but "misspelled". will be removed soon.




[ Top ]

method complement [line 788]

array complement( mixed $arrayA, mixed $arrayB, array $array)



Tags:

return:  (see example)
see:  Bs_Array::intersect()


Parameters:

array   $array   (hash or vector)

[ Top ]

method copyValuesToKeys [line 688]

array copyValuesToKeys( mixed $arr)

copies the value of an array to the key. then key/value are the same.

this is useful do deal with select fields and the Bs_FormFieldSelect class.

note: make sure you don't have a value twice, it would remove one element. note: this does not work for boxed arrays.

example: $a = array('0'=>'foo', '1'=>'bar', '2'=>'php'); $a = $Bs_Array->copyValuesToKeys(); now $a is: array('foo'=>'foo', 'bar'=>'bar', 'php'=>'php');




Tags:

since:  bs4.3
throws:  empty array


[ Top ]

method diff [line 772]

array diff( mixed $arrayA, mixed $arrayB, array $array)



Tags:

return:  (see example)
see:  Bs_Array::intersect()


Parameters:

array   $array   (hash or vector)

[ Top ]

method explode [line 52]

array explode( array $separator, mixed $string, [mixed $limit = 0], string $string )

similar to php's explode but can explode on multiple strings at once.

example: you want to explode on ' ' and '-' at once. crap. with this method it's a nap. $result = Bs_Array->explode(array(' ', '-'), 'this is your-string'); will give you array('this', 'is', 'your', 'string')

you can also just do $result = split('[ -]', 'this is your-string'); thus i'm not sure if that method is needed at all :/ (thanks to rick).




Tags:

todo:  support the limit param.


Parameters:

array   $separator  
string   $string    //@param int $limit (default is 0 which means 'no limit'.)

[ Top ]

method getLastKey [line 458]

mixed getLastKey( array $array)

Get the last (highest) key from an array.

if $array is an associative array, it's the last one. if $array is a 'normal' indexed array, it's an int.

note: if you're going to pass the $array param by reference, be aware of the fact that this method moves the pointer to the end.




Tags:

return:  the last/highest key, so it's an int or a string.


Parameters:

array   $array  

[ Top ]

method getPos [line 514]

int getPos( array $array, mixed $find, [bool $findKey = TRUE], [bool $ignoreCase = FALSE])

returns the numeric position of a given key or value in the given array.

the position starts with 0, not 1.

example: $array = array(3=>'viola', 7=>'sam', 9=>'rick', 12=>'fab'); $pos = $Bs_Array->getPos($array, 7); //will return 1 $pos = $Bs_Array->getPos($array, 'RICK', FALSE, TRUE); //will return 2




Tags:

return:  (0-n)
throws:  bool FALSE (if not found)


Parameters:

array   $array  
mixed   $find   (the value to find)
bool   $findKey   (where to look, TRUE means key while FALSE means value.)
bool   $ignoreCase   (if you want to ignore the case for the compare. default is FALSE.)

[ Top ]

method guessType [line 561]

string guessType( array $array)

Guess the array type. associative or not.

arrays in php are great fun. but there's one thing.. these 2 arrays are exactly the same, so once created you cannot tell the difference: array('0'=>'foo', '1'=>'bar') array('foo', 'bar') even the fact that '0' and '1' were written as strings and not 0 and 1 as integers does not help; they are converted.

it's possible and i can think of cases where someone creates an associative array with integer keys, they don't need to be strings.

if the key is not numeric, it's 100% sure that it's associative. if it's numeric, and the first key has the value 0, we return a guessed zero-based. otherwise a guessed associative-based.

note: if you're going to pass the $array param by reference, be aware of the fact that this method moves the pointer to somewhere out in the green ...

example: if (substr($Bs_Array->guessType($myArray), 0, 6) == 'vector') echo 'most likely a vector';




Tags:

return:  one of 'hash', 'vector', 'hash_guess', 'vector_guess'
throws:  NULL if param is not an array at all, FALSE if array is empty.


Parameters:

array   $array  

[ Top ]

method hashKeysToLower [line 632]

hash &hashKeysToLower( int &$hashArray, array $rowPos)

*********************************************************************** Transform all keys of a hash array to lower case NOTE: If 2 keys have the same value after modification, the second overwrites the first.



Tags:

return:  array with all keys to lower case
deprecated:  use the new php function array_change_key_case() (PHP 4 >= 4.2.0 2002/03/12 --andrej)


Parameters:

array   $rowPos  
int   &$hashArray  

[ Top ]

method hashKeysToUpper [line 656]

hash &hashKeysToUpper( int &$hashArray, array $rowPos)

*********************************************************************** Transform all keys of a hash array to upper case NOTE: If 2 keys have the same value after modification, the second overwrites the first.



Tags:

return:  array with all keys to upper case
deprecated:  use the new php function array_change_key_case() (php4 cvs only 2002/03/12 --andrej)


Parameters:

array   $rowPos  
int   &$hashArray  

[ Top ]

method inArray [line 346]

bool inArray( string $needle, array $haystack, [bool $ignoreCase = TRUE], [bool $ignoreSpaces = TRUE])

tells if the value $needle is a value of the array $haystack.

similar to php's in_array() function but this one is used for strings only and is able to ignore case and/or spaces. the 'strict' param is of no use here. if you don't need ignorecase or ignorespaces then you are better off with php's function, which must be faster.

moves the pointer of $haystack, but does not change values. so you may pass the array by reference.

example: $array = array('abc', ' HELLO '); inArray('hello'); returns TRUE.




Tags:

todo:  maybe preg would be faster here than converting. dunno. at the moment i'm happy.


Parameters:

string   $needle  
array   $haystack  
bool   $ignoreCase   (case insensitive search.)
bool   $ignoreSpaces   (spaces (etc) in $haystack and $needle are ignored using trim().)

[ Top ]

method intersect [line 755]

array intersect( mixed $arrayA, mixed $arrayB, array $array)

Similar to PHP's array_diff and array_intersect but is consequent when using hash-arrays.

The array-set function here, look at key-value pairs e.g. it distinguashes between C=>c and E=>c. PHP's array-set function array_diff, array_intersect *IGNOR* the keys and only look at the values, thus PHP's array_intersect considers C=>c and E=>c to be the same.

Sample: Given are 2 hash-arrays: $A = array(A=>a, B=>b, C=>c, D=>d, a) $B = array(A=>v, B=>b, D=>d, E=>c)

Set-Diagram of A and B the way we look at it. A _____ _____ B .-"" ""-.-"" ""-. / / \ \ / / \ \ . A=>a . . A=>v . | | B=>b | | | | D=>d | | . C=>c . . E=>c . \ \ / / \ [0]=>a \ / / . __ __ . __ __ . """"" """"" The difference to PHP's array_diff and array_intersect :

PHP's array_intersect($A, $B) | Bs_Array::intersect($A, $B) ------------------------------------+----------------------------- array(B=>b, C=>c, D=>d) | array(B=>b, D=>d)

PHP's array_diff($A, $B) | Bs_Array::diff($A, $B) ------------------------------------+----------------------------- array(A=>a, a) | array(A=>a, C=>c, a)

-- missing -- | Bs_Array::complement($A, $B) ------------------------------------+-----------------------------

  • | array(A=>v, C=>c, a, E=>c)




Tags:

return:  (see example)


Parameters:

array   $array   (hash or vector)

[ Top ]

method max [line 390]

mixed max( array $array, [string $what = 'value'])

returns the highest number that exists in the array.

only values that are numeric are taken into account. and this is the difference to: http://www.php.net/manual/en/ref.array.php david@preform.dk 01-Feb-1999 12:30 use the max function to get the highest value of an array e.g: $maxval = max($array); php's min() and max() treats bool FALSE as the smallest value. we only use numeric values.

note I: this method moves the pointer of the array. you may pass the param by ref. note II: not using php's sort functions here. maybe code may be speed-optimized. note III: if 2 or more numbers are equal (and the max) and you want the 'key' returned then only the first key is returned.

php offers array_sum() but not this. i guess it will be there somewhen.

example: $array = array('en'=>5, 'fr'=>7, 'de'=>3); $maxNum = max($array); $maxLang = max($array, 'key');




Tags:

return:  (for 'value': double for 'key': string)
see:  $this->min(), php's max() and array_sum()
throws:  bool FALSE (if not an array, or no numeric value at all.)


Parameters:

array   $array   vector or hash holding numbers
string   $what   (one of 'value' (default) or 'key' which means if you want the key or value of the max element returned.)

[ Top ]

method maxSizeOfLevel [line 80]

int maxSizeOfLevel( array $array, int $level)

returns the max size of elements of an array

example: $array = array(

  1. => array('one', 'two', 'three'),
  2. => array('one', 'two'),
  3. => array('one', 'two', 'three', 'four')
) maxSizeOfLevel($array, 1) will return 3, that's like a sizeOf(). maxSizeOfLevel($array, 2) will return 4.

it makes no sense to use $level=1.




Tags:

throws:  int 0 if $array is not an array or empty.


Parameters:

array   $array  
int   $level  

[ Top ]

method merge [line 118]

array merge( array 0)

merges 2 arrays.

this is similar to php's array_merge, but behaves a bit different: php's function sucks in that it fucks up the keys (index) of the arrays sometimes. read the user comments on php.net about it.

example: $arrOne = array(''=>''); $arrTwo = array('9'=>'apple', '15'=>'banana', '20'=>'grapefruit'); $result = array_merge($arrOne, $arrTwo); now $result is array(''=>'', '0'=>'apple', '1'=>'banana', '2'=>'grapefruit'); in php 4.1.1 (see ecg 'syntax' file) $result = Bs_Array->merge($arrOne, $arrTwo); now $result is array(''=>'', '9'=>'apple', '15'=>'banana', '20'=>'grapefruit');

as for array_merge: If the input arrays have the same string keys, then the later value for that key will overwrite the previous one. so: if you want to merge 2 numeric arrays and don't care about the index (keys) then you have to use array_merge().

if one of the given params is not an array, it will be ignored.




Tags:

return:  (may be empty)


Parameters:

array   0   (takes 0-n arrays as params. may be hashes or vectors.)

[ Top ]

method min [line 423]

mixed min( array $array, [string $what = 'value'])

returns the smallest number that exists in the array.

see $this->max() there is more information.




Tags:

return:  (for 'value': double for 'key': string)
see:  $this->max(), php's min() and array_sum()
throws:  bool FALSE (if not an array, or no numeric value at all.)


Parameters:

array   $array   vector or hash holding numbers
string   $what   (one of 'value' (default) or 'key' which means if you want the key or value of the max element returned.)

[ Top ]

method padding [line 607]

void &padding( $array $array, [$pad_string $pad_string = ' '], [$pad_length $pad_length = 0], [$pad_type $pad_type = STR_PAD_RIGHT])

This functions pads the input array of strings on the left, the right, or both sides to the specifed padding length. If length is 0 or not set, the size of longest string in the array will be used as length.

Optional argument pad_type can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT. NOTE: You may pass array by reference for direct changes.




Tags:

see:  PHP-doc str_pad()


Parameters:

$array   $array   see above
$pad_string   $pad_string   (opt) see above (default ' ')
$pad_length   $pad_length   (opt) see above (default 0)
$pad_type   $pad_type   (opt) see above (default STR_PAD_RIGHT) return array

[ Top ]

method randVal [line 824]

mixed randVal( array $array)

Return one of the given elements of the array randomly.

note: maybe you better use php's array_rand() for your needs.

if no or an empty array was given, an empty string is returned.

example: $hello = 'world'; $foo = 'bar'; $x = $Bs_String::randVal(array(&$hello, &$bar));

it's intentional that the param $array is taken by value and not by reference. this way you can use a syntax like the one above in the example. otherwise you'd have to do $x = $Bs_String::useOneOfArray($array = array($hello, $bar)); which is less optimized especially for big array elements.




Tags:

return:  a randomly selected element of the array, by value.
todo:  maybe make use of the new php function array_rand() internally.
see:  useOneOf()


Parameters:

array   $array   any array you can think of.

[ Top ]

method reindex [line 856]

&$array &reindex( array &$arr, [int $startPos = 0])

reindexes the given array.

note: the array will be reset, so remember the current position yourself if you need to.




Tags:

todo:  implement $startPos feature if needed.
access:  public


Parameters:

array   &$arr  
int   $startPos   (default is 0. note: not implemented yet.)

[ Top ]

method setPos [line 482]

bool setPos( array &$array, mixed $findKey)

sets the pointer to the given key (hash or vector) we hope that php comes with such a function sometime.



Tags:

return:  TRUE if key was found, FALSE if not (pos will be after the last element)


Parameters:

array   &$array   (hash or vector)
mixed   $findKey   (int or string)

[ Top ]

method splitKeyValue [line 709]

array splitKeyValue( array $array)

returns the keys and values of the given array separated in 2 arrays.

example: $array = ('name'=>'fab', 'sex'=>'m'); list($keys, $values) = splitKeyValue($array); //now $keys = array('name', 'sex') and $values = array('fab', 'm')




Tags:

return:  (see example)


Parameters:

array   $array   (hash or vector)

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:08:01 +0100 by phpDocumentor 1.2.3